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.

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
suppressed	Address or email appears on a set list of suppressions
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 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.

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.

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.