Skip to main content

Webhooks

Lynq delivers outbound HTTPS POST requests to URLs you register. Payloads use a Stripe-style envelope signed with HMAC-SHA256.

Subscribe​

POST /webhooks with your HTTPS URL. Response 201 Created includes:

  • id — webhook subscription ULID
  • secret — shown once; store in your secrets manager
{
  "url": "https://your-company.example.com/webhooks/lynq",
  "description": "Production listener",
  "event_filters": []
}

Empty event_filters receives all catalog events. Otherwise only listed types are delivered.

Headers​

HeaderPurpose
X-Lynq-Signaturet=<unix>,v1=<hex> over {t}.{raw_body}
X-Lynq-EventEvent type (mirrors JSON type)
Content-Typeapplication/json

Verification algorithm​

  1. Read the raw body bytes (before JSON parsing re-serialization).
  2. Parse t and v1 from X-Lynq-Signature.
  3. Compute HMAC-SHA256(secret, "{t}.{raw_body}") as lowercase hex.
  4. Compare with v1 using a constant-time compare.

Use the Tools page or verification snippets for reference implementations.

Envelope shape​

{
  "id": "01EVTEXAMPLE0000000000000001",
  "object": "event",
  "created": 1715000000,
  "livemode": false,
  "type": "order.delivered",
  "data": {
    "object": {
      "id": "01ORDER…",
      "status": "delivered"
    }
  }
}

Retries and idempotency​

Failed deliveries retry with backoff. The same logical event reuses the same envelope id. Record processed IDs to prevent duplicate fulfillment in your OMS.

Test and replay​

  • POST /webhooks/\{id\}/test — synthetic webhook.test event
  • Replay endpoints (see API reference) enqueue historical events for backfill

Event catalog​

Autogenerated reference pages live under Webhook Events.