Guide: How To Use Webhooks

Webhooks

Webhooks allow you to subscribe to events that happen within the Stannp Direct Mail platform. We will send a HTTP POST request to the webhook’s configured URL. Webhooks can be used to update any external software or notify you on key events such as the day a mailpiece is expected to be delivered.

Please be aware our webhooks service is currently in preview. This means there could be breaking changes in the coming weeks.

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 despatched 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: 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.

Creating a webhook

You can find the page to create and manage your webhooks here. To create a webhook you must provide a name, url, content type and events to subscribe to.

When you save the webhook we will send a test request to the URL you provided. If the request responds with a 200 HTTP code we will mark the webhook as active. The test request will send a payload which will look like the following.

{
   "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.

{
   "webhook_id":1234,
   "event":"mailpiece_status",
   "created":"0000-00-00 00:00:00",
   "retries":"0",
   "mailpieces":[
      {
         ...[mailpiece object]... 
      }
   ]
}

Notice that the payload will always contain an array of objects that have been triggered, even if just one item. This is because a it’s often that the events could be triggered simultaneously for many objects. The objects name will depend on the events subscribed eg mailpieces, campaigns or recipients.

You can see a list of object types in our object reference documentation page.