Webhooks

​

Setting up Webhooks

1. Register the URL of an endpoint to receive webhooks
2. Receive a secret signing key that will be generated and shared with you and is essential for ensuring the authenticity of incoming payloads and preventing malicious requests

​

Using Webhooks

​

Request Headers

• webhook-id: An ID that uniquely identifies each message.
• webhook-timestamp: A Unix timestamp indicating when the event was signed. This timestamp is included in the signature to guard against replay attacks. See Verifying Events for more details.
• webhook-signature: A list of signatures (HMAC-SHA256) created using a secret signing key and will be used to validate the authenticity of an event. Typically, the signature list consists of only one element, but it can contain any number of signatures. It is formatted as a space delimited list of signatures and their corresponding version identifiers. See Verifying Events for more details. For example:
  Copy

  Ask AI

  v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo=
  

​

Processing Events

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• Additional 10 hours

​

Verifying Events

• Ensure the webhook-timestamp is within a valid time window (we recommend up to 3 minutes).
• Since retries generate a new timestamp for each attempt, you can confidently validate each request.
• Reject requests with timestamps outside the threshold to block tampered or replayed events.

• Generate the signed content by concatenating the values of thewebhook-id request header, webhook-timestamp request header, and a string representation of the request body into a single string, separated by periods.
• Calculate the expected signature, using the secret key and the signed content above to generate a HMAC SHA256 signature. Then, encode this value using a base64 encoding.
• Verify the signature by comparing the expected signature above above with the signature sent in the webhook-signature header. If the generated signature matches the provided signature, you can proceed with processing the event.

​

Structure of an Event

• id : An ID that uniquely identifies each event.
• type: The type of event that triggered the webhook, for example, payment_session.created or payment_session.updated events
• data: The actual payload, which can be a different object depending on the event type. For example, for payment_session.* events, the payload will always be the payment_session object.

​

Handling Duplicate Events

• If the payment_session (as identified by the payment session identifier) is already in a final state, for example, completed, expired, or canceled; or a payment (as identified by the payment identifier) is already in a final state, for example, succeeded, ignore the event by responding with a 2xx status code to prevent redelivery — since no further state change is needed.
• Only apply updates that move the object forward, for example:
  • payment_session: active → completed
  • payment: draft → succeeded

​

Additional Security Precautions

52.215.16.239
54.216.8.72
63.33.109.123
2a05:d028:17:8000::/56

​

Sample Code

// Using NodeJs + Express
app.post("/my/webhook/url", function(req, res) {
    const requestBody = req.rawBody;

    // TODO: Verify and process the received data

    res.send(200);
});

// Using NodeJs + Express
const headers = req.headers;
const requestBody = req.rawBody;

const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];

const signedContent = `${id}.${timestamp}.${requestBody}`;

const crypto = require('crypto');

const secret = 'whsec_MDUyYmQ2NThjZDY3NDU5NzkyYTViNjViOTlhYzI2MzE=';
const secretBytes = Buffer.from(secret.split("_")[1], "base64");

const expectedSignature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent)
    .digest('base64');

// Compare just the first signature
const signature = headers['webhook-signature'].split(' ')[0].split(',')[1]
if (crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(signature))) {
    // process webhook event
    return res.send(200);
}
// do not process webhook event
return res.send(403);

const express = require('express');
const crypto = require('crypto');
const getRawBody = require('raw-body');

const app = express();

app.use((req, res, next) => {
    getRawBody(req, {
        length: req.headers['content-length'],
        encoding: 'utf-8'
    }, (err, rawBody) => {
        if (err) return next(err);
        req.rawBody = rawBody;
        next();
    });
});

app.post("/my/webhook/url", function(req, res) {
    const headers = req.headers;
    const requestBody = req.rawBody;

    // Construct the signed content
    const id = headers['webhook-id'];
    const timestamp = headers['webhook-timestamp'];

    const signedContent = `${id}.${timestamp}.${requestBody}`;

    // Determine the expected signature
    const secret = 'whsec_M0U0MDI3QjYzMEQ0NTK5NDNCIjVFMENCMDEzNzc1QkE=';
    const secretBytes = new Buffer(secret.split('_')[1], "base64");

    const expectedSignature = crypto
        .createHmac('sha256', secretBytes)
        .update(signedContent)
        .digest('base64');

    // Compare just the first signature
    const signature = headers['webhook-signature'].split(' ')[0].split(',')[1]
    if (crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(signature))) {
        // process webhook event
        return res.send(200);
    }
    // do not process webhook event
    return res.send(403);
});

app.listen(3000, () => {
    console.log('Server is running on port 3000');
});