Best practices

​

HTTP code 2XX

The webhook target URL must always respond with a 2XX HTTP code.

This is to ensure the communication went right. Business logic errors are not to be handled using HTTP error codes.

​

Response times

The target URL must respond fast. Expected delay of response is less than 500ms.

A grace delay of less than a second may be authorized in exceptional cases.

This is to maintain an optimal quality of service. Live webhooks with longer delays won’t be permitted.

​

Asynchronous handling

In order to achieve these response times, there are simple mechanisms that can be put in place. Among other things, it’s strongly encouraged to process webhooks asynchronously upon reception and immediately response with an HTTP 2xx code.

Example in javascript:

async function onPaymentIntentCreatedWebhookReceived(req, res) {
   await this.verifyHub2WebhookSignature(req);
   this.handlePaymentIntentCreated(req); // async method, event queue ...
   res.send('""');
   res.status(201).end(); // Send HTTP 2xx right away
}

​

Split events to multiple webhooks

If a single webhook is registered with all events, its deactivation will prevent all these events to be sent.

A good practice to avoid that behavior is to register a single event per webhook, so any deactivation won’t make the other webhooks to stop working too.