Postworks API Webhooks

What are webhooks?

Webhooks allow you to subscribe to certain events that happen in Postworks. When one of these events is triggered we’ll send a HTTP POST payload to the webhook’s configured URL.

Events

Currently, only one event category exists and covers Send only. More categories will be added in the future.

The available events are:

Event Category	Event Type	Description
Send	UPDATE	When an item updates status

Payloads

The JSON payload will be a consistent format for all categories of events. It will consist of:

The Items array	The details of the events that you’ve subscribed to
Date	The sequence number of the last event in this payload
Entropy	A random string to make the payload more cryptographically secure

Each Item will consist of:


URN	The Unique Reference Number of the item
Status	The status of the item
CreatedDate	The Created Date of the item
UpdatedDate	The last Updated Date of the item

Example payload

1. If the client has the ClearSend® function enabled:

{
  "Items": [
  
    {

      "IsClearSendCertified": false,
   
      "ClearSendCertifiedDate": null,

      "URN": "220420000006R",

      "Status": 1,

      "CreatedDate": "2022-04-23T14:01:55.567",

      "UpdatedDate": "2022-04-23T14:01:56.9"


    },

    {

      "IsClearSendCertified": true,
   
      "ClearSendCertifiedDate": "2022-04-22T09:02:16.623",

      "URN": "220420000007K",

      "Status": 5,

      "CreatedDate": "2022-04-20T14:02:16.303",

      "UpdatedDate": "2022-04-23T14:02:16.623"


    }

  ],
  
  "Date": "2022-04-23T14:05:00:280",
  
  "Entropy": "zyzipoxq5h"
}

2. If the client does not have the ClearSend® function enabled:

{

  "Items": [

    {

      "URN": "220420000006R",

      "Status": 1,

      "CreatedDate": "2022-04-20T14:01:55.567",

      "UpdatedDate": "2022-04-20T14:01:56.9"

    },

    {

      "URN": "220420000007K",

      "Status": 1,

      "CreatedDate": "2022-04-20T14:02:16.303",

      "UpdatedDate": "2022-04-20T14:02:16.623"

    }

  ],

  "Date": "2022-04-20T14:05:00:280",

  "Entropy": "zyzipoxq5h"

}

The Signature header

A hashed signature of the payload is passed along in the headers of each request as Signature. This signature is used when doing an intent to receive validation.

Creating a webhook

To create a webhook for your app you need to visit the Account Admin section of HUB and click Webhooks - https://hub.postworks.co.uk/AccountAdmin/Webhooks

All you need to do is input the URL where you want the payload delivered:

Note: Your URL must be HTTPS

Click create and your webhook is created. You’ll need to take note of the Webhook Key which is used when doing an intent to receive validation.

When your webhook is first created the status will be ‘Intent to receive’ required.

The webhooks status


‘Intent to receive’ required	Your webhook subscription has just been created and events won’t be delivered until the intent to receive validation is started. Updating your delivery url and re-enabling a disabled subscription will also place you in this status.
‘Intent to receive’ in progress	Intent to receive validation is in progress. This can take up to 30 seconds to complete. If it fails, the status will go back to ‘Intent to receive’ required and you will have to click the Validate ‘Intent to receive’ button to retry.
OK	Webhooks are being delivered successfully.
Retry	We haven’t received a successful response on the most recent delivery attempt and will retry sending with decreasing frequency for an overall period of 24 hours.
Disabled	We haven’t received a successful response after retrying for 24 hours and the webhook is now disabled. Click the Re-enable webhooks button to re-activate your subscription.

Configuring your server

Once you’ve created the webhook you’ll need to set up your server to receive the HTTP POST requests at the endpoint you specified. There are just a few basic things that we expect from your endpoint

It uses HTTPS on the standard 443 port
It responds within 5 seconds with a 200 OK status code
There is no body in the response
There are no cookies in the response headers
If the signature is invalid a 401 Unauthorised status code is returned

If we don’t receive an acceptable response when sending events we will continue retrying the request, with decreasing frequency for up to 24 hours. After 24 hours the webhook will be disabled and needs to be re-enabled.

If you want to test webhooks in your local dev environment, you can use online webhooks testers, like https://webhook.site/

Intent to receive

To ensure the requests you receive are coming from Postworks you need to verify the signature provided in the Signature header. When creating or re-enabling a webhook subscription (or updating the subscription url) the user will be prompted to start an ‘Intent to receive’ validation. This validation process will be a series of HTTPS POST requests to the url provided in the subscription.

All validation requests will look like this:

Example payload

{

  "Items": [ ],

  "Date": "2022-04-20T14:01:00:220",

  "Entropy": "yzzisoxw3b"

}

If the payload is hashed using HMACSHA256 with your webhook signing key and base64 encoded, it should match the signature in the header. This is a correctly signed payload. If the signature does not match the hashed payload it is an incorrectly signed payload.

To gain Intent to receive validation, the receiving url must respond with status: 200 Ok for all correctly signed payloads and respond with status: 401 Unauthorised for all incorrectly signed payloads.

It must also respond within the guidelines of all webhook requests listed above.

If the validation is passed, the status displayed in the console will change from Intent to receive in progress to OK. If the validation fails, the status will return to Intent to receive required and the last delivery attempt time and fail reason is displayed in the console. Another intent to receive validation can be requested in the console.

Delivery Failures

When you fail to respond correctly to a webhook we will immediately retry. Any subsequent retry attempts will be spaced out by 15 minutes until a successful response is given.

If after 24 hours we still have not received a successful response we will disable your subscription.

Once the issue has been resolved you can re-enable your subscription and complete the ITR process to continue receiving your webhooks.

Any events that happen while your subscription is in the Retry or Disabled states will be saved for up to 10 days and replayed in order once your subscription is healthy again.