Webhook

Introduction

If you run your own web application server, you can easily add real-time payment event processing with a webhook.

You can create one in the client area under Notifications -> Webhooks.

It's a simple form that takes two parameters:

Form

Field	Description
URL	The URL to which we will send HTTP POST requests when payment events occur.
Events	The types of events you want to receive. You can choose to receive all events, or only specific event types.

Events you can choose from include:

Event types

Event Name	Description
payment_detected	Sent when a payment is detected but not yet confirmed, and the invoice status changes to "Confirming"
payment_confirmed	Sent when a payment is fully confirmed and the invoice status changes to "Paid"
payment_failed	Sent when a payment fails and the invoice status changes back to "Unpaid"

Message verification

After you create a webhook, you immediately receive a secret, unique to that webhook, which can be used in your application to verify that messages received are authentic.

Requests will be signed with a header called signature.

We employ HMAC-SHA512.

Code examples

const secret = 'SHARED_SECRET';

const body = req.body;
const receivedSignature = req.headers['signature'];

const computedSignature = crypto
  .createHmac('sha512', secret)
  .update(JSON.stringify(body))
  .digest('hex');

if (receivedSignature !== computedSignature) {
  return res.status(401).send('Unauthorized');
}

At payment event

When a qualifying event occurs, your webhooks will receive an HTTP POST request containing a JSON payload and a signature header which can be used to verify the authenticity of the message.

Example Event Payload

{
  "event": "payment_confirmed",
  "invoice_id": "12345",
  "status": "Paid",
  "payment_id": "6789"
}

Webhook Body Schema

Field	Type	Description
invoice_id	string	The ID of the invoice.
status	string	The status of the invoice. Possible values are "Paid", "Confirming", and "Failed".
event	string	The type of event
payment_id	string	The ID of the payment triggering this event associated with the invoice.

Webhook request headers

Field	Type
signature	string

Your webhook should respond with a 200 - OK HTTP status code to acknowledge successful event handling.
If your webhook does not respond with a 200 status code, we will retry event delivery for up to 3 days, with an increasing delay between attempts.

On this page