Generic outgoing webhook

The escape hatch. After payment, the glue POSTs the order + buyer payload to your URL. Your service does the rest (provision a license, create a tenant, ship a physical package, whatever).

What it does

The entitlement worker sends a signed POST with Content-Type: application/json. On non-2xx response or timeout the job retries with exponential backoff up to 5 attempts; after that the entitlement is marked failed and the merchant sees it in the dashboard.

Prerequisites

• A publicly reachable HTTPS endpoint (or use a tunneled URL in dev — ngrok / Cloudflare Tunnel).
• A way to verify HMAC-SHA256 signatures.

Step-by-step

1. In the dashboard, add an entitlement of type Webhook to your product:

   • URL: https://your-service.example.com/openbitum/payment
   • Headers (optional): Authorization: Bearer …

2. Save. The next purchase will POST:

   {
     "event": "entitlement.webhook",
     "orderId": "ord_01H9...",
     "productId": "prd_01H9...",
     "user": { "id": "lgto_...", "email": "buyer@example.com" },
     "paidAt": "2026-05-11T12:34:56Z",
     "amount": "49.00",
     "currency": "USDC",
     "txHash": "0xabc..."
   }
   

3. Verify the signature on your side. Pseudocode (Node):

   import crypto from "node:crypto";
   const sig = req.headers["x-openbitum-signature"];
   const expected = crypto
     .createHmac("sha256", process.env.OPENBITUM_WEBHOOK_SECRET)
     .update(rawBody)
     .digest("hex");
   if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
     return res.status(401).end();
   }
   

   The shared secret is GLUE_OUTBOUND_WEBHOOK_SECRET from your .env.

Idempotency

Each delivery includes X-OpenBitum-Delivery-Id (UUID). Store these on your side and return 200 if you see a repeat — retries can produce duplicates.

Troubleshooting

| Symptom | Likely cause | |---|---| | Retries keep happening | your endpoint returned non-2xx, or didn't respond within 10 s | | Signature mismatch | your OPENBITUM_WEBHOOK_SECRET differs from .env | | No delivery at all | check the order detail page → entitlement.failed entry; full error is in docker compose logs glue |

Coming after MVP launch

Per-entitlement custom signing secrets, replay protection via timestamp window, and a delivery-log inspector in the dashboard.