Configuring Webhooks

Postscript uses webhooks to send out events that happen on our platform. You may view all webhook events available here.

What are webhooks

A webhook is a way for Postscript to send out real-time notifications to you. We do this by sending HTTPS POST requests with a JSON payload to an endpoint of your choosing. You can then use these events to do things in your application.

Use Cases

Receiving a Shop's Subscriber Messages

You can use Postscript webhooks to receive messages that have been sent to a shop in your application. That means that whenever a new message has been sent from a subscriber to a shop, your application can receive that as an event (shop.incoming_message) that your application can process and do something with (like sending back a response via our Send Message API).

Receiving a Shop's Subscriber's Lifecycle

You can use Postscript webhooks to receive updates about subscriber lifecycle events for a shop. For example, you can subscribe to receive events every time a subscriber opts in (shop.subscriber.opt_in). You can also receive events every time a subscriber opts out (shop.subscriber.opt_out).

Steps to receive webhooks

1. Create a webhook endpoint on your local server.
2. Set up handling events from Postscript.
3. Register your endpoint with Postscript.
4. Test that your endpoint is working.
5. Go live with your endpoint.

Step 1: Creating a webhook endpoint on your server

In order to receive webhooks, you'll have to have to set up a place where we can send them. You can do this by simply creating a basic HTTP endpoint on your local machine. What this might look like if you were using Python and Flask is:

@app.route('/postscript_webhooks', methods=['POST'])
def webhook():
    payload = request.json

You could also choose to use a third party service, like Zapier, that can receive webhooks as well.

Step 2: Handling Postscript webhook events

In order to handle Postscript webhook events, you'll want to check the event object and send us back a 200 response.

The event object that we will send you, will look something like the below:

{
  "webhook_id": "89066f0a-eb36-4ed8-b98c-606e6dcac715",
  "resource_type": "shop",
  "resource_id": "shop_1234567abcd",
  "event_time": "2021-11-04T21:52:41.025455",
  "event": "shop.incoming_message",
  "event_data": {
  	  "id": "im_1b2a005a386281c9",
      "subscriber_id": "s_1234567abcd",
      "shop_id": "shop_1234567abcd",
      "is_opt_out": false,
      "shopify_customer_id": null,
      "from_number": "+15555555555",
      "created_at": "2021-11-04T21:52:41.025455",
      "body": "Hello, world"
  }
}

You'll want to parse this object on your server to make sure it is the correct event you are looking for shop.incoming_message and for any event_data you need to do in your application.

Once you have parsed the information and handled in your application, you'll want to send us back a 200 response (we will ignore the body of that response). Best practice is to do this before doing any complex application logic in order to make sure we get the response in a timely manner and don't retry to send you the event again.

Another best practice to keep in mind as you're developing your application is that it is possible the same event with the same information gets sent as an event to your server more than once. This can happen for a variety of reasons but you can avoid issues by making sure your application is idempotent, meaning, when you get the same event, with the same data, no matter how many times you get it, your application handles it in the same way.

Retry strategy

If we do not get back a 200 status code, or it takes a long time to receive this response, we will retry to send you the event again. We will retry with the following strategy:

• Every 5 mins (until we get a 200 response)
• For up to 1 hour

Security

To ensure that the requests sent to your endpoint are genuinely from Postscript, you need to implement some security measures. Since anyone on the internet can send a request, it's essential to verify the authenticity of incoming requests.

• You will need to retrieve the webhook signing token specific to the Postscript account by making a call to the Get Webhook Signing Token API. This token should be stored securely, as it will be used to verify requests.
• When Postscript sends a request to your endpoint, it will include a Postscript-Signature header as part of the request. You should compare the token retrieved from the API with the value of this header. If the values match, the request is verified as coming from Postscript. If the header is missing or the values don't match, the request should be treated as suspicious and not processed.

Step 3: Registering your endpoint

In order to get webhooks to the endpoint you have set up, you'll need to let us know about it. To create a new webhook subscription, use the Create Webhook Subscription endpoint. You'll have to send us the url where you want the webhooks sent to (as callback_url) and the event you want to subscribe to (shop.incoming_message for example).

curl --request POST \
     --url https://api.postscript.io/api/v2/webhooks \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer [API TOKEN]' \
     --header 'Content-Type: application/json' \
     --data '
{
     "callback_url": "https://custom.endpoint.url",
     "event": "shop.incoming_message"
}
'

Step 4: Testing your endpoint

Once you've got your endpoint set up and registered, you can test it out by sending a test message to the shop it is registered for. You should receive the shop.incoming_message event at your registered endpoint.

You can also test webhooks by using our Test Shop Webhook endpoint.

Step 5: Going live

Once you're confident that everything is working properly and you're ready to go live, you're done! All you have to do is let your customers know 😄 !