Skip to main content

Developers: Webhooks

What It Is​

Webhooks provide async event delivery to your endpoint when subscribed events occur.

Where It Is Managed​

  • Settings -> Developers -> Webhooks

Dashboard Management​

Create endpoints, subscribe to events, rotate secrets, enable or disable delivery, send test events, and inspect deliveries from the dashboard.

Receiver Requirements​

  • Verify webhook signatures from X-EshopOS-Signature.
  • Enforce replay window by timestamp.
  • Process idempotently by event ID.
  • Return 2xx only after durable acceptance.

Signature Verification​

Each signed delivery includes:

  • X-EshopOS-Signature-Timestamp: Unix timestamp in seconds.
  • X-EshopOS-Signature: t=<timestamp>,v1=<hex_hmac_sha256>.

Compute the expected v1 value with HMAC-SHA256 using your one-time webhook signing secret over:

<timestamp>.<raw request body>

Reject requests when the timestamp is outside your replay window or when the HMAC comparison fails. If an older webhook endpoint does not receive signature headers, rotate its secret once from the dashboard so encrypted signing material is available.