Webhooks

Flashpay uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like payment status updates.

The Webhook Event

When an event occurs, we send a HTTP POST request to your configured webhook URL. The request body contains the Payment object in JSON format.

Example Payload

{
    "id": "pay_123456789",
    "amount": 5000,
    "currency": "NGN",
    "status": "SUCCESSFUL",
    "reference": "ref_987654321",
    "description": "Payment for Order #123",
    "ownerId": "bus_123",
    "destinationAccount": "1234567890",
    "destinationAccountName": "John Doe",
    "createdAt": "2023-11-25T10:00:00Z",
    "updatedAt": "2023-11-25T10:05:00Z"
}

Security

We sign every webhook event so you can verify that it was sent by Flashpay.

Headers

Every webhook request includes the following headers:

Header	Description
`X-Webhook-Signature`	The HMAC-SHA256 signature of the request.
`X-Webhook-Timestamp`	The Unix timestamp (in seconds) when the webhook was sent.

Verifying Signatures

Extract the headers: Get X-Webhook-Signature and X-Webhook-Timestamp.

Construct the signed content: Concatenate the timestamp, a dot (.), and the raw request body.

signed_content = "{timestamp}.{raw_body}"

Generate the expected signature: Compute an HMAC-SHA256 signature of signed_content using your Webhook Secret as the key.

Compare signatures: Compare your generated signature with the X-Webhook-Signature header.

[!IMPORTANT]
To prevent replay attacks, verify that the X-Webhook-Timestamp is within a 5-minute tolerance of your server time.

Example (Node.js)

Retries

If your server returns a non-2xx response, we will retry the webhook delivery 3 times with exponential backoff.

Attempt 1: Immediate

Attempt 2: +100ms

Attempt 3: +200ms

Attempt 4: +400ms

If all retries fail, we stop sending the event.

Webhooks

Webhooks#

The Webhook Event#

Example Payload#

Security#

Headers#

Verifying Signatures#

Example (Node.js)#

Retries#

Webhooks

The Webhook Event

Example Payload

Security

Headers

Verifying Signatures

Example (Node.js)

Retries