Webhook events and payloads

Learn about when each webhook event occurs and what the payload contains.

About webhook events and payloads

You can create webhooks that subscribe to the events listed on this page. Each webhook event on this page includes a description of the webhook properties for that event. If the event has multiple actions, the properties corresponding to each action are included. For more information, see "Creating webhooks."

Note: Payloads are capped at 25 MB. If an event generates a larger payload, Shopwaive will not deliver a payload for that webhook event. We suggest monitoring your payload size to ensure delivery.

Delivery headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

• X-Shopwaive-Hook-ID: The unique identifier of the webhook.

• X-Shopwaive-Event: The name of the event that triggered the delivery.

• X-Shopwaive-Delivery: A globally unique identifier (GUID) to identify the delivery.

• X-Shopwaive-Signature-256: This header is sent if the webhook is configured with a secret. This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret as the HMAC key. For more information, see "Validating webhook deliveries."

• X-Shopwaive-Hook-Installation-Target-Type: The type of resource where the webhook was created.

• X-Shopwaive-Hook-Installation-Target-ID: The unique identifier of the resource where the webhook was created.

To see what each header might look like in a webhook payload, see "Example webhook delivery."

Example webhook delivery

Following is an example of a webhook POST request that uses the JSON format.

> POST /payload HTTP/2

> X-Shopwaive-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> X-Shopwaive-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> Content-Type: application/json
> Content-Length: 6615
> X-Shopwaive-Event: available_balance
> X-Shopwaive-Hook-ID: 292430182
> X-Shopwaive-Hook-Installation-Target-ID: 79929171
> X-Shopwaive-Hook-Installation-Target-Type: organization

> {
>   "action": "redeemed",
>   "event": {
>        "available_balance": {
>            "pre": "53.40",
>            "post": "28.40"
>        },
>    },
>   "transaction": "25.00",
>   "order_id": 230984933,
>   "customer_email": "[e-mail]",   
>   "organization" : {
>     "id": 1296269,
>     "url": "https://dianas-toys-and-such.myshopify.com",
>     "platform": "shopify",
>     "currency": "$",
>     "contactEmail" "[e-mail]"
>   }
> }

Events

Events (i.e. subscription topics) are permission-controlled Shopwaive resources that can be shared with external sites or applications using webhooks, which deliver payloads at a url that you define. Payloads are delivered when you have an active subscription and an event action (i.e. event trigger) occurs for that resource.

available_balance

This event occurs when there is activity relating to a customer's available balance. For information about the APIs to manage a customer's available balance, see Customer API in the REST API documentation.

To subscribe to this event, a Shopwaive App must have at least read-level access for the "Available balance" organization permission.

Availability for available_balance

• Organizations

• Shopwaive Apps

Webhook payload object for available_balance

Action type: deleted, adjusted, redeemed, or created

An available balance was <action-type> for a customer.

Webhook request body parameters

action string Required

The action that was performed.

Value: deleted, adjusted, redeemed, or created

available_balance object Required

The available balance itself

Properties of available_balance

pre string Required The customer's available balance prior to the webhook event.

post string Required The current customer's available balance (i.e. after the webhook event).

transaction string Required

The transaction amount associated with the webhook action.

order_id string Optional

Order id associated with webhook event (only available if action is redeemed)

customer_email string Required

Customer email associated with the webhook event.

organization object Optional

A Shopwaive e-commerce entity or organization. Is included when the target type associated with the webhook installation is organization.

Properties of organization

id string Required The organization's id on file with Shopwaive.

url string Required The organization's root domain on file with Shopwaive.

platform string Optional The organization's website builder platform (if applicable).

currency string Optional The organization's currency setting defined in Shopwaive.

contactEmail string Optional The organization's contact email on file with Shopwaive.