# Webhook events and payloads

### [About webhook events and payloads](#about-webhook-events-and-payloads) <a href="#about-webhook-events-and-payloads" id="about-webhook-events-and-payloads"></a>

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.](/reference/creating-webhooks.md)"

**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](#delivery-headers) <a href="#delivery-headers" id="delivery-headers"></a>

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)"

#### [Example webhook delivery](#example-webhook-delivery) <a href="#example-webhook-delivery" id="example-webhook-delivery"></a>

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

```bash
> 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": "support@shopwaive.com",   
>   "organization" : {
>     "id": 1296269,
>     "url": "https://dianas-toys-and-such.myshopify.com",
>     "platform": "shopify",
>     "currency": "$",
>     "contactEmail" "sales@dianas.com"
>   }
> }
```

## [Events](#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](#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](https://api.shopwaive.com/reference/rest-api-documentation/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  *<mark style="color:orange;">Required</mark>* |
| ------------------------------------------------------------------- |
| The action that was performed.                                      |
| Value: `deleted`, `adjusted`, `redeemed`, or `created`              |

| **`available_balance`**  object  *<mark style="color:orange;">Required</mark>* |
| ------------------------------------------------------------------------------ |
| The [available balance](#available_balance) itself                             |

<details>

<summary>Properties of <code>available_balance</code></summary>

**`pre`**  string  *<mark style="color:orange;">Required</mark>* The customer's available balance prior to the webhook event.

**`post`**  string  *<mark style="color:orange;">Required</mark>* The current customer's available balance (i.e. after the webhook event).

</details>

| **`transaction`**  string  *<mark style="color:orange;">Required</mark>* |
| ------------------------------------------------------------------------ |
| 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  *<mark style="color:orange;">Required</mark>* |
| --------------------------------------------------------------------------- |
| 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`**. |
|                                                                                                                                                 |

<details>

<summary>Properties of <code>organization</code></summary>

**`id`**  string  *<mark style="color:orange;">Required</mark>* The organization's id on file with Shopwaive.

**`url`**  string  *<mark style="color:orange;">Required</mark>* 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.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://webhooks.shopwaive.com/reference/webhook-events-and-payloads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.