Skip to main content
MasterID delivers event notifications to a public HTTPS endpoint that you configure in the Developer Console. Your receiver must verify each payload using the one-time signing secret, accept events durably and deduplicate by event ID. Webhooks are an alternative to polling for final verification and collection results.

Setup and constraints

  1. Open the Developer Console and add one public HTTPS webhook URL.
  2. Securely store the one-time signing secret immediately. Secrets cannot be recovered after the first display is closed.
  3. To replace the URL or signing secret, delete the current webhook and add another.
Redirects and private network destinations are not supported.

Events

Request headers

Verify the signature

1

Read the raw request body

Read the request body as raw bytes or a string before any JSON parsing. Parsing first can change whitespace and invalidate the signature.
2

Compute the expected signature

Compute the HMAC-SHA256 using your signing secret over the string timestamp + '.' + rawBody. Produce a lowercase hex digest.
3

Compare in constant time

Compare the computed signature against the X-MasterID-Signature header using a constant-time comparison function. Reject the request if they do not match.
4

Check the timestamp

Reject events with a timestamp older than 5 minutes relative to your server time.
5

Parse JSON after verification

Only parse the request body as JSON after the signature and timestamp have passed validation.
6

Deduplicate

Track processed X-MasterID-Event-ID values and skip duplicates.
7

Accept durably

Persist or enqueue the event durably, then return any HTTP 2xx response. Do not return a success status before you have accepted the event.

Retry schedule

MasterID retries failed deliveries up to five total attempts. API History records each attempt’s HTTP status. If callbacks are unavailable, poll saved references as a recovery path.
Completion notifications and background retries require the published release.

Receiver examples

Each example reads the signing secret from the environment, performs constant-time comparison, enforces the 5-minute timestamp window, deduplicates by event ID and returns 200 after durable acceptance.

Integration checklist

Public HTTPS endpoint

Your URL must be reachable from the internet over HTTPS with a valid certificate.

Raw body preservation

Read the exact raw body before JSON parsing to preserve the signature input.

Constant-time compare

Use crypto.timingSafeEqual or hmac.compare_digest to avoid timing attacks.

Timestamp tolerance

Reject events with a timestamp older than 5 minutes to prevent replay attacks.

Deduplicate events

Track X-MasterID-Event-ID and skip duplicates. Delivery is at least once.

Durable acceptance

Write or queue the event before returning HTTP 2xx. Do not trust repeated events as new operations.

Fallback path

If your webhook receiver is unavailable, poll saved references as a recovery path: