About webhooks

Webhooks provide a way for notifications to be delivered to an external web server whenever certain events occur on Shopwaive.

About webhooks

Webhooks are a method of communication that allows users to subscribe to events happening in a software system. Webhooks can be triggered whenever specific events occur on Shopwaive. For example, you can configure a webhook to trigger whenever:

• Customer available_balance change triggered by redemption (i.e. customer places order)

• Customer available_balance change triggered by adjustment (i.e. admin adjusts credit for existing customer)

• Customer available_balance change triggered by created event (i.e. admin issues credit for new customer)

• Customer available_balance change triggered by deletion (i.e. admin deletes credit)

• Customer available_balance change for all actions (this is the default config i.e. deleted, adjusted, redeemed, refund, imported, rest_api, expired, or created actions)

• Order invoice_url created with credit applied

• Customer places an order with credit

• Customer email sent from action (i.e. campaign_sent or manually_sent)

Currently, you can create webhooks for Shopify stores or Headless sites using Shopify headless infrastructure with Shopwaive.

You can create up to 5 webhooks for each event on each installation target (specific site or domain).

For more information about creating webhooks, see "Creating webhooks."

Note: Shopwaive webhooks do not currently support IPv6 but will in the future.

About webhook events

When configuring a webhook, you can choose which events will send you payloads. To limit the number of HTTP requests to your server, you should only subscribe to the specific events that you plan on handling. For a complete list of webhook events and their payloads, see "Webhook events and payloads"

Some webhook events have actions, which are operations that can be performed on the resource that the webhook event represents. If a webhook event has multiple action types, each action will trigger a payload delivery. For example, the available_balance webhook event will trigger a payload delivery when a customer's available balance is either deleted, adjusted, redeemed, or created. You cannot subscribe to individual webhook actions. When you configure a webhook, you will receive payloads for all of the actions related to that webhook.

By default, webhooks on Shopwaive Apps are not subscribed to any events. You can change events that a webhook is subscribed to at any time.

About webhook deliveries

When you receive a webhook delivery, the payload will contain the name of the event and action that triggered the delivery, along with other information about the event itself. For more information about the delivery headers that are included with each payload, and an example delivery, see "Webhook events and payloads." Some information is included in most or all webhook deliveries, such as the user who performed the event, or the organization or repository where the event occurred.

When you create a webhook, you will need to specify a URL where you want to receive the webhook events. Shopwaive will send a HTTP POST payload to this URL when any events that the webhook is subscribed to occur. Your server can then process and respond to the webhook. For more information, see "Handling webhook deliveries."

Note: Payloads are capped at 25 MB. If your event generates a larger payload, a webhook will not be fired. We suggest monitoring your payload size to ensure delivery.

For information on viewing webhook deliveries, see "Viewing webhook deliveries."

When to use webhooks

Webhooks can be used in a wide range of scenarios, including:

• Trigger marketing automations and integrate with internal tools and processes. For example, to trigger a customer-facing email campaign connected to a third-party provider (i.e. Zapier, Klaviyo, or Mailchimp).

• Send email notifications about customer activity (i.e. customer's available balance is updated) to an account executive (AE) or internal sales team.

• Updating an external issue tracker like Jira.

• Deploying to a production server.

• Logging events as they happen on Shopwaive, for audit purposes.

Webhooks allow you to receive data as it happens, as opposed to calling an API intermittently to see if data is available, also known as polling for updates. You only need to express interest in an event once, when you create the webhook.

Webhooks have the following advantages over using the API:

• Webhooks require less effort and less resources than polling an API.

• Webhooks scale better than API calls. If you need to monitor many resources, calling the API for each resource may cause you to hit your API rate limit quota quickly. Instead, you can subscribe to multiple webhook events and receive information only when an event happens.

• Webhooks allow near real-time updates, since webhooks are triggered when an event happens.

If you only need information once or intermittently or only want to get information from a small set of resources with no plans to scale up, you can call the API when you need the relevant information.

For information on best practices to follow when using webhooks, see "Best practices for using webhooks."

About permissions for managing webhooks

To manage webhooks, you must own or have admin access to the resource that the webhook is created on and listening for events on. For example, to manage organization webhooks you need admin permissions for that organization entity, such as for a website or ecommerce site built on a website builder platform. For more information about creating different webhook types, see "Creating webhooks."