Webhooks

Learn how to listen to events whenever certain actions occur on your integration.

What are webhooks?

Whenever certain transaction actions occur on your Paystack integration, we trigger events which your application can listen to. This is where webhooks come in. A webhook is a URL on your server where we send payloads for such events. For example, if you implement webhooks, once a payment is successful, we will immediately notify your server with a charge.success event. Here is a list of events we can send to your webhook URL.

Helpful Tip
We recommend that you use webhook to provide value to your customers over using a callback. Callbacks can fail if the network connection on a customer's device fails or is weak or if the device goes off after a transaction and several other situations that are outside both our and your control.

You can specify your webhook URL on your dashboard where we would send POST requests to whenever an event occurs.

Here are some things to note when setting up a webhook URL:

  1. If using .htaccess, remember to add the trailing / to the url you set.
  2. Do a test post to your URL and ensure the script gets the post body.
  3. Ensure your webhook URL is publicly available (localhost URLs cannot receive events)

Receiving an event

All you have to do to receive the event is to create an unauthenticated POST route on your application. The event object is sent as JSON in the request body.

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

Verifying events

It is important to verify that events originate from Paystack to avoid delivering value based on a countefeit event.

You can do any or both of the below to verify events from Paystack:

  1. Validate the Signature - Valid events are raised with an header X-Paystack-Signature which is essentially a HMAC SHA512 signature of the event payload signed using your secret key.
  2. Watch the IPs - We only call your webhooks from these IPs: 52.31.139.75, 52.49.173.169, 52.214.14.220

You can whitelist these IPs. Any webhook from outside of these can safely be considered counterfeit.

Show Response
1var crypto = require('crypto');
2var secret = process.env.SECRET_KEY;
3// Using Express
4app.post("/my/webhook/url", function(req, res) {
5 //validate event
6 var 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 var event = req.body;
10 // Do something with event
11 }
12 res.send(200);
13});
1

Responding to an event

You should respond to an event with a 200 OK. We consider this an acknowledgement by your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it every hour for 72 hours. You don't need to send a request body or some other parameter as it would be discarded - we only pay attention to the status code.

If your application is likely to start a long running task in response to the event, Paystack may timeout waiting for the response and would ultimately consider the event unacknowledged and queue to be raised later. You can mitigate duplicity by having your application respond immediately with a 200 before it goes on to perform the rest of the task.

Supported events

1{
2 "event": "subscription.create",
3 "data": {
4 "domain": "test",
5 "status": "active",
6 "subscription_code": "SUB_vsyqdmlzble3uii",
7 "amount": 50000,
8 "cron_expression": "0 0 28 * *",
9 "next_payment_date": "2016-05-19T07:00:00.000Z",
10 "open_invoice": null,
11 "createdAt": "2016-03-20T00:23:24.000Z",
12 "plan": {
13 "name": "Monthly retainer",
14 "plan_code": "PLN_gx2wn530m0i3w3m",
15 "description": null,
16 "amount": 50000,
17 "interval": "monthly",
18 "send_invoices": true,
19 "send_sms": true,
20 "currency": "NGN"
21 },
22 "authorization": {
23 "authorization_code": "AUTH_96xphygz",
24 "bin": "539983",
25 "last4": "7357",
26 "exp_month": "10",
27 "exp_year": "2017",
28 "card_type": "MASTERCARD DEBIT",
29 "bank": "GTBANK",
30 "country_code": "NG",
31 "brand": "MASTERCARD"
32 },
33 "customer": {
34 "first_name": "BoJack",
35 "last_name": "Horseman",
36 "email": "[email protected]",
37 "customer_code": "CUS_xnxdt6s1zg1f4nx",
38 "phone": "",
39 "metadata": {},
40 "risk_action": "default"
41 },
42 "created_at": "2016-10-01T10:59:59.000Z"
43 }
44}

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.

EventDescription
charge.successA successful charge was made
subscription.createA subscription has been created
subscription.disableA subscription on your account has been disabled
subscription.enableA subscription on your account has been enabled
invoice.createAn invoice has been created for a subscription on your account. This usually happens 3 days before the subscription is due or whenever we send the customer their first pending invoice notification
invoice.updateAn invoice has been updated. This usually means we were able to charge the customer successfully. You should inspect the invoice object returned and take necessary action
invoice.failedAn invoice has not been created for the subscription because the customer's payment for the subscription failed
transfer.successA successful transfer has been completed
transfer.failedA transfer you attempted has failed
customeridentification.successA customer ID validation was successful
customeridentification.failedA customer ID validation has failed
transfer.reversedA transfer you attempted has been reversed
paymentrequest.pendingA payment request has been sent to a customer
paymentrequest.successA payment request has been paid for