Webhooks catalog

1. Why webhooks (not polling)

Polling the API to check for state changes is wasteful: 99% of requests return "no change," and the 1% that matter arrive minutes late. Webhooks invert the model — HIBR pushes events to your endpoint within 5 seconds of the underlying state change.

For UAE-specific workflows, webhooks matter especially for:

• Payment confirmation: Know within seconds when a customer pays — trigger your own fulfillment.
• VAT 201 submission status: Know within minutes whether FTA accepted the return.
• WPS bank acknowledgement: Know within hours whether the bank rejected any SIF row.
• E-invoice delivery: Know within seconds whether the customer received the PINT-AE invoice via PEPPOL.

2. Event payload shape

Every webhook delivery is an HTTPS POST with a stable JSON payload structure:

# Standard event envelope
POST https://your-endpoint.com/hibr-webhook HTTP/1.1
Content-Type: application/json
Hibr-Event: invoice.paid
Hibr-Event-Id: evt_01HFQB...
Hibr-Signature: t=1729000080,v1=5257a86...
Hibr-Webhook-Endpoint: wh_01HFQA...

{
  "id": "evt_01HFQB...",
  "object": "event",
  "type": "invoice.paid",
  "created": "2026-10-15T09:32:14Z",
  "api_version": "2026-10-01",
  "livemode": true,
  "data": {
    "object": {
      / Full invoice resource at the moment of the event
      "id": "inv_01HFQB...",
      "object": "invoice",
      "status": "paid",
      ...
    },
    "previous_attributes": {
      / Only changed fields, for diff calculation
      "status": "open"
    }
  }
}

Key fields:

• id — unique event ID (idempotency key on your side)
• type — event type from the catalog (§7)
• data.object — the resource at the moment of the event
• data.previous_attributes — only fields that changed (useful for diff-based logic)
• livemode — true for production, false for sandbox

HIBR expects your endpoint to respond with HTTP 2xx within 10 seconds. Slower than 10 seconds counts as a failed delivery and triggers retry. Anything other than 2xx counts as a failed delivery.

3. Signature verification

Every webhook is signed with HMAC-SHA256 using a secret shared at subscription time. Verify the signature before processing the payload — otherwise an attacker who knows your endpoint URL could send forged events.

Signature header format

Hibr-Signature: t=1729000080,v1=5257a86a9eb1d77a4d3c7e2f9b8a6c5e4d3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8

• t — Unix timestamp of when HIBR computed the signature
• v1 — HMAC-SHA256 hex digest of {timestamp}.{raw_body} using your endpoint secret

Verification procedure

1. Extract t and v1 from the Hibr-Signature header.
2. Verify timestamp tolerance — reject if t is more than 5 minutes old (replay protection).
3. Recompute the expected signature: HMAC-SHA256(secret, "{t}.{raw_request_body}").
4. Constant-time compare against v1. Reject if mismatch.

# Node.js example
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const parts = Object.fromEntries(signature.split(',').map(p => p.split('=')));
  const t = parts.t, v1 = parts.v1;

  / Replay protection — 5-minute window
  if (Math.abs(Date.now()/1000 - parseInt(t)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(v1)
  );
}

4. Retry policy

If your endpoint fails to respond with 2xx within 10 seconds, HIBR retries with exponential backoff. Up to 8 attempts spanning 72 hours.

After attempt 8, the event is marked permanently failed. Permanent failures are retrievable via the replay endpoint (§5) for 30 days.

Endpoints that fail 100 consecutive deliveries are automatically disabled, with an email notification to the developer contact. Re-enable from the dashboard.

5. Replay & manual redelivery

Every event delivered (or attempted) is retrievable for 30 days. Useful for:

• Reprocessing a webhook your handler crashed on
• Backfilling state after a deployment that missed events
• Debugging why your signature verification rejected a particular event

6. Managing webhook endpoints

Webhook endpoints are first-class resources. Manage them via API or in the dashboard.

Endpoint object

{
  "id": "wh_01HFQA...",
  "object": "webhook_endpoint",
  "url": "https://your-server.com/hibr",
  "description": "Production payment processor",
  "enabled_events": ["invoice.paid", "payment.succeeded"],
  "status": "enabled",
  "created": "2026-10-15T09:32:14Z",
  "secret": "whsec_..." / only on creation + rotate
}

7. Event catalog

32 event types at launch, grouped by resource. Subscribe to specific events or use wildcards (e.g., invoice.*).

8. Security best practices

• Always verify signatures. If you skip this, you're trusting the network. Don't trust the network.
• Treat the endpoint secret like a database password. Store it in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler), not in source code or environment files committed to git.
• Rotate secrets periodically. Use the rotate-secret endpoint. You can have two active secrets at once during rotation (old + new) for zero-downtime rotation.
• Use idempotency on your side too. Webhook events have a stable id — store the ID of each processed event and reject duplicates. Retries can deliver the same event twice.
• Respond fast. Acknowledge with 2xx as soon as you've verified the signature and queued the work — don't do heavy processing in the webhook handler. Process the queued work asynchronously.
• Use IP allowlisting where you can. All HIBR webhook deliveries originate from a fixed set of egress IPs published at https://api.hibr.ai/security/egress-ips (post-launch). Restrict your endpoint to only accept connections from this list at the firewall.
• Log everything in dev / staging. Especially during integration. The dashboard's delivery log shows the request/response pairs HIBR saw, but your own logs are necessary for debugging your handler.