Webhooks

The Webhooks feature enables you to receive real-time events directly from our server. You can configure each webhook to subscribe to specific events of your choice. When an event occurs, we will send an HTTP POST request to your specified URL.

How to add a Webhook

1. Navigate to the Webhooks page in the Dashboard: https://dashboard.paytweed.com/webhooks

2. Click on + Add Webhook

3. Enter your endpoint URL (the https:// prefix will be added automatically, as we only support secure connections). Ensure your endpoint is publicly accessible so our server can send requests to it.

4. For enhanced security, you can specify a signing secret. [See Signing Secret.]

5. Select events that this Webhook would be listening to (at least 1).

Tip: You may create multiple Webhooks one for each event, or one webhook listening to all the events that interest you.

Signing Secret

The signing secret is a shared string used to verify that incoming webhook requests are authentic and have not been tampered with or spoofed. This ensures that the request is genuinely coming from our server. Make sure the signing secret you provide is stored securely and encrypted in your platform (for example, using AWS secret manager).

We use HMAC-based shared-key authentication for this purpose. The signing process involves generating a signature using the shared key and comparing it with the one included in the webhook request.

// TypeScript

const signingSecret: string = '<the secret>';
const algorithm = 'sha256';
const result = `${algorithm}=${createHmac(algorithm, signingSecret)
    .update(payload)
    .digest('hex')}`

// >>> console.log(result)
// sha256=4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865

We then attach the result in the request headers under the X-Hub-Signature-256 header: Example header:

X-Hub-Signature-256: sha256=4355a46b19d348dc2f57c046f8ef63d4538ebb936000f3c9ee954a27460dd865

Later on your end, you may validate by using the same implementation (hashing the HTTP request body) and compare the result with the header.

For increased security use a cryptographically-secure string comparison function like: crypto.timingSafeEqual

Read more: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries

Headers sent in a webhook call

Those are the headers sent in each webhook call:

'X-Tweed-Hook-ID': string // a unique id of the webhook
'X-Tweed-Event': string // the event identifier
'X-Tweed-Delivery': string // for replay attacks prevention. client can ignore the same delivery id if already processed
'X-Hub-Signature-256'?: string // signature of the payload + secret

X-Tweed-Hook-ID

Each webhook you create on the platform is assigned a unique identifier, which remains consistent across all requests for that specific webhook. This identifier is included in the request headers to help you differentiate between webhooks if you manage multiple endpoints.

This can help you identify which webhook triggered the request. Ensures you can route or handle requests appropriately based on the webhook's unique ID. Once a webhook is created, its identifier remains unchanged and is included in every request associated with that webhook. Make sure your system logs or processes this header to track and manage incoming webhook events effectively.

X-Tweed-Event

Each webhook request includes a header named X-Tweed-Event, which contains the unique identifier for the specific event being reported. This allows you to track and manage individual events efficiently.

X-Tweed-Delivery

The X-Tweed-Delivery header contains a unique identifier for each webhook delivery. This ensures idempotency and helps prevent replay attacks by allowing clients to identify and ignore duplicate requests. Use the delivery ID to make event handling idempotent, ensuring the same event is not applied multiple times.

X-Hub-Signature-256

The X-Hub-Signature-256 header contains the cryptographic signature of the webhook payload, generated using the HMAC-SHA256 algorithm with your shared secret. This header allows you to verify the authenticity and integrity of the webhook request. [See Signing Secret]

Available Events

All the events will include those common body fields:

{
    "platformId": string, // Unique identifier of your platform
    "timestamp": number, // In UNIX epoch format
}

Additionally to the common parameters each event will have more parameters based on the event context.

Checkout Success

Called after a transaction is finalized.

{
    "checkoutId": "string",
}