Webhooks
Webhooks allow you to subscribe to events that happen within the Stannp Direct Mail platform. We will send an HTTP POST request to the webhook's configured URL. Webhooks can be used to update any external software or notify you of key events such as the day a mailpiece is expected to be delivered.
Creating a Webhook
Webhooks can be created and managed on the webhooks page which can be found in your Stannp account settings.
On first creation of a webhook, we will send a test request to the URL you provide, looking for an HTTP 200 status. If this is not received, your webhook will not be created.
Validation Request Body
{
"webhook_id": 0,
"event": "test_url",
"created": "2024-01-15 10:30:00",
"retries": 0
}Webhook Payload
When a webhook is triggered we send a request to the specified URL. The request will include a payload in the following format.
The payload will always contain an array of objects that have been triggered, even if just one item. This is because it's often that the events could be triggered simultaneously for many objects. The object's name will depend on the events subscribed, e.g., mailpieces or campaigns.
You can see a list of object definitions in our object reference documentation page.
The array key name in the payload varies by event type: mailpieces for mailpiece_status, campaigns for campaign_status, and events for recipient_events.
Webhook Payloads
{
"webhook_id": 1234,
"event": "mailpiece_status",
"created": "2024-01-15 10:30:00",
"retries": 0,
"mailpieces": [
{
"...": "[mailpiece object]"
}
]
}Webhook Security
We offer the option for signed webhook events. To enable this is simple, you must set a secret when initially creating your webhook. We recommend using a random string with high entropy; however, this can be whatever you like.
When you have a secret token set, the signature can be found in the X-Stannp-Signature header. The hash for the signature is generated with an HMAC digest using sha256.
Validating Payloads
To validate that the request has come from Stannp you will need to first recreate the hash by hashing the raw message body against your stored secret. This can then be compared against the hash sent with the request.
We strongly recommend using a proper hash comparator method, such as PHP's hash_equals() rather than a plain == operator.
Request Example
curl "your_webhook_url" \
-u {API_KEY}: \
-H "X-Stannp-Signature: signature_value"Triggerable Events
When configuring your webhook you can choose which events to subscribe to. When that event occurs, the webhook will be triggered.
Parameters
| Parameter | Details | Description |
|---|---|---|
| campaign_status | webhook event optional | Triggers whenever a campaign status changes. Status codes: printing, dispatched, cancelled. |
| mailpiece_status | webhook event optional | Triggers whenever a mailpiece status changes. Status codes: printing, dispatched, cancelled, local_delivery, delivered, returned. |
| recipient_events | webhook event optional | Triggers whenever a new recipient event is recorded. |
Delivery Behaviour
Webhook deliveries have the following operational characteristics.
Parameters
| Parameter | Details | Description |
|---|---|---|
| Payload Chunking | info behaviour info | If an event triggers for more than 50 objects, the payload is split into multiple webhook calls, each containing up to 50 objects. |
| Retry Logic | info behaviour info | Failed deliveries are retried up to 3 times with a 30-second delay between attempts. The retries field reflects the current attempt number. |
| Auto-Pause | info behaviour info | If a webhook endpoint fails 5 or more times within a 24-hour period, the webhook is automatically paused. You will need to manually resubscribe via the platform. |