Best practices

Apply these recommendations before going live.

HTTP code 2xx

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

The status code only confirms that the webhook was received. Do not use HTTP error codes to report business logic errors.

Response times

The target URL should respond fast. Aim for a response time of less than 500 ms; up to one second is acceptable occasionally. These are recommendations, not enforced limits.

HUB2 waits at most 5 seconds for a response. A slower response counts as a failed delivery and the event is retried, which can eventually disable the webhook (see Behavior).

Asynchronous handling

Simple mechanisms help you meet these response times. In particular, verify the signature, hand the webhook over to asynchronous processing (an event queue, for example) and respond with a 2xx code immediately.

JavaScript example:

function onPaymentIntentCreatedWebhookReceived(req, res) {
   verifyHub2WebhookSignature(req); // throws if the signature is invalid
   enqueuePaymentIntentCreated(req.body); // processed asynchronously, not awaited
   res.status(200).end(); // respond with 2xx right away
}

Split events across several webhooks

If a single webhook is registered with all events, its deactivation stops the delivery of all of them.

To avoid this, register one event per webhook: if one webhook is disabled, the others keep working.