Webhooks

Introduction

Generally, when you make a request to an API endpoint, you expect to get a near-immediate response. However, some requests may take a long time to process, which can lead to timeout errors. In order to prevent a timeout error, a pending response is returned. Since your records need to be updated with the final state of the request, you need to either:

1. Make a request for an update (popularly known as polling) or,
2. Listen to events by using a webhook URL.

Polling vs Webhooks

Polling requires making a GET request at regular intervals to get the final status of a request. For example, when a customer makes a payment for a transaction, you keep making a request for the transaction status until you get a successful transaction status.

With webhooks, the resource server, Paystack in this case, sends updates to your server when the status of your request changes. The change in status of a request is known as an event. You’ll typically listen to these events on a POST endpoint called your webhook URL.

The table below highlights some differences between polling and webhooks:

Create a webhook URL

A webhook URL is simply a POST endpoint that a resource server sends updates to. The URL needs to parse a JSON request and return a 200 OK:

1// Using Express
2app.post("/my/webhook/url", function(req, res) {
3    // Retrieve the request's body
4    const event = req.body;
5    // Do something with event
6    res.send(200);
7});

When your webhook URL receives an event, it needs to parse and acknowledge the event. Acknowledging an event means returning a 200 OK in the HTTP header. Without a 200 OK in the response header, we’ll keep sending events for the next 72 hours:

• In live mode, we’ll send webhooks every 3 minutes for the first 4 tries, then we switch to sending hourly for the next 72 hours
• In test mode, we send webhooks hourly for the next 72 hours

Verify event origin

Since your webhook URL is publicly available, you need to verify that events originate from Paystack and not a bad actor. There are two ways to ensure events to your webhook URL are from Paystack:

1. Signature validation
2. IP whitelisting

Signature validation

Events sent from Paystack carry the x-paystack-signature header. The value of this header is a HMAC SHA512 signature of the event payload signed using your secret key. Verifying the header signature should be done before processing the event:

1const crypto = require('crypto');
2const secret = process.env.SECRET_KEY;
3// Using Express
4app.post("/my/webhook/url", function(req, res) {
5    //validate event
6    const hash = crypto.createHmac('sha512', secret).update(JSON.stringify(req.body)).digest('hex');
7    if (hash == req.headers['x-paystack-signature']) {
8    // Retrieve the request's body
9    const event = req.body;
10    // Do something with event  
11    }
12    res.send(200);
13});

IP whitelisting

With this method, you only allow certain IP addresses to access your webhook URL while blocking out others. Paystack will only send webhooks from the following IP addresses:

1. 52.31.139.75
2. 52.49.173.169
3. 52.214.14.220

You should whitelist these IP addresses and consider requests from other IP addresses a counterfeit.

Go live checklist

Now that you’ve successfully created your webhook URL, here are some ways to ensure you get a delightful experience:

1. Add the webhook URL on your Paystack dashboard
2. Ensure your webhook URL is publicly available (localhost URLs cannot receive events)
3. If using .htaccess kindly remember to add the trailing / to the URL
4. Test your webhook to ensure you’re getting the JSON body and returning a 200 OK HTTP response
5. If your webhook function has long-running tasks, you should first acknowledge receiving the webhook by returning a 200 OK before proceeding with the long-running tasks
6. If we don’t get a 200 OK HTTP response from your webhooks, we flagged it as a failed attempt
7. In the live mode, failed attempts are retried every 3 minutes for the first 4 tries, then we switch to sending hourly for the next 72 hours
8. In the test mode, failed attempts are retried hourly for the next 72 hours

Supported events

1{
2  "event": "customeridentification.failed",
3  "data": {
4    "customer_id": 82796315,
5    "customer_code": "CUS_XXXXXXXXXXXXXXX",
6    "email": "email@email.com",
7    "identification": {
8      "country": "NG",
9      "type": "bank_account",
10      "bvn": "123*****456",
11      "account_number": "012****345",
12      "bank_code": "999991"
13    },
14    "reason": "Account number or BVN is incorrect"
15  }
16}

Types of events

Here are the events we currently raise. We would add more to this list as we hook into more actions in the future.