# Webhooks

Webhooks allow you subscribe to certain events relating to your mailings, such as delivery notification, exception, etc... When one of those events is triggered, we'll send a HTTP POST to the webhook's configured URL. Webhooks can be used to update an external system such as a CRM or marketing automation tool.

Webhooks can be set up at an account level, just navigate to **API > Webhooks** to get started. You can create up to 10 webhooks. Once setup, the webhook will be triggered each time an event occurs on any mailing within your account.

### Payload

Webhooks contain a `JSON` payload with the following fields.

| Field         | Description                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `object_id`   | The ID of the object to which the webhook relates. For mailings, this would be the mailing `id`.       |
| `object_type` | The type of the object to which the webhook relates. For mailings, this will be `Mailing`              |
| `event`       | A string describing the event which triggered the webhook. In the case of Mailing's, an event is fired |
| `timestamp`   | An ISO 8601 formatted timestamp indicating when the event occurred.                                    |

### Headers

HTTP `POST` payloads contain an `X-SLM-Signature` HTTP header. This is the HMAC hex digest of the response body. It is generated using the SHA1 hash function with the secret displayed on the **API > Webhooks** page as the HMAC key. You can use this in order to verify the authenticity and integrity of a payload.

```http
POST /endpoint HTTP/1.1
Content-Length:	131
Content-Type: application/json
User-Agent: SLM/1.2
X-SLM-Signature: 205610e3f868a33d2a9fed113bb7c79e3d56c4bc

{
  "object_id": "ffe27528-adea-496a-ba2b-23cde9d70b97",
  "object_type": "Mailing",
  "event": "mailed",
  "timestamp": "2019-02-22T15:15:39Z"
}
```

### Events

Each event corresponds to the state of a mailing:

| Event                     | Description                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `append_failed`           | Unable to append a physical address to email                                                                                 |
| `address_invalid`         | Invalid address data [*learn more*](https://docs.heypoplar.com/article/207-address-validation)                               |
| `suppressed`              | Address or email appears on a set list of [suppressions](https://docs.heypoplar.com/article/204-suppression-settings)        |
| `budget_exceeded`         |                                                                                                                              |
| `credit_balance_exceeded` |                                                                                                                              |
| `processing`              | Confirming all details of the mailing and production                                                                         |
| `mailed`                  |                                                                                                                              |
| `delivered`               | Scanned as delivered                                                                                                         |
| `delivery_exception`      | Delivery will make a second attempt                                                                                          |
| `failed`                  | Indicates a fatal issue which prevents the mailing from being processed                                                      |
| `holdout`                 | Not mailed as part of the [holdout](https://docs.heypoplar.com/article/67-what-is-a-holdout-group-how-do-i-set-one-up) group |

### Retry Policy

If the server does not return a HTTP **200** Success response code, we will retry the `POST` up to 10 times using an exponential backoff strategy.

{% hint style="warning" %}
Webhooks which continue to fail after exhausting their retry attempts will be automatically disabled and will need to be re-enabled manually from the dashboard.
{% endhint %}

### Testing

When you create a webhook, we'll send a simple `ping` event to test connectivity. You can also trigger them from the webhooks list.