Webhooks

A webhook tells another system the moment something happens in WHBMP.

Create one

1. Open Settings > API & Webhooks.
2. Add a webhook with a name, the URL that should receive the events and the events you want.
3. WHBMP gives you a secret used to sign each request.

Events

The request

Each event is a POST with a JSON body and two headers:

• X-WHBMP-Event: the event name, for example invoice.paid
• X-WHBMP-Signature: the HMAC-SHA256 of the raw request body, using your webhook secret

Verify the signature

Always check it before trusting the data. In PHP:

$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, $secret);

if (! hash_equals($expected, $_SERVER['HTTP_X_WHBMP_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Compute the hash over the raw body, not over re-encoded JSON.

Delivery log

Every attempt, successful or not, is recorded under the webhook's deliveries with the response status, so you can see why a delivery failed. Answer with a 2xx status quickly and do heavy work afterwards.

Tips

• Use HTTPS endpoints only.
• Make your handler idempotent: the same event can arrive more than once.
• Webhooks are sent at the moment the action happens, one attempt each. A failed delivery is logged but not retried, so combine webhooks with a periodic read through the REST API if you cannot miss an event.