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
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": "0000-00-00 00:00: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, campaigns, or recipients.
You can see a list of object definitions in our object reference documentation page.
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, campaigns, or recipients.
You can see a list of object definitions in our object reference documentation page.
Standard Webhook Payload
{
"webhook_id": 1234,
"event": "mailpiece_status",
"created": "0000-00-00 00:00: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
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
We strongly recommend using a proper hash comparator method, such as PHP's
hash_equals() rather than a plain == operator.Example Request Validation
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "your_webhook_url?api_key={API_KEY}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => array(
),
CURLOPT_HTTPHEADER => array(
"X-Stannp-Signature: signature_value"
),
));
$response = curl_exec($curl);
curl_close($curl);
print_r($response);
?>
Triggerable Events
Events are when something happens within the Stannp platform. Common events include status changes to a campaign or individual mailpiece. When configuring your webhook you can choose which events to subscribe to. Then when that event happens, such as a campaign has been dispatched, the webhook will be triggered. Currently you can subscribe to the following events.
Campaign Status: This event triggers whenever the campaign status changes. Status codes include:
Mailpiece Status: This event triggers whenever the mailpiece status changes. Status codes include:
Recipient Blacklisted: This event triggers whenever a recipient has been blacklisted.
Recipient Event: This event triggers whenever a new recipient event is recorded.
Campaign Status: This event triggers whenever the campaign status changes. Status codes include:
producing, dispatched, cancelled.Mailpiece Status: This event triggers whenever the mailpiece status changes. Status codes include:
producing, dispatched, cancelled, local_delivery, delivered, returned.Recipient Blacklisted: This event triggers whenever a recipient has been blacklisted.
Recipient Event: This event triggers whenever a new recipient event is recorded.