Best practices
These recommendations must be applied before the traffic can go live.
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.
Please note, those deadlines may be reduced in the future.
Notices will be sent far ahead in case it happens, especially to the slowest integrations to response to the webhook requests.
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.