# 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.


---

# 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://docs.heypoplar.com/api/webhooks.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.