Skip to content

Receive Webhooks

Use webhooks when your app needs to react to SigID events after they happen. Examples include login, membership, organization, application, security, or audit changes.

Do not use webhooks for the immediate login response. Login still returns through the browser callback. Webhooks are for asynchronous updates.

What You Build

  1. Create an HTTPS endpoint in your backend.
  2. Register the endpoint in SigID.
  3. Store the signing secret server-side.
  4. Verify the webhook signature before trusting the event.
  5. Check timestamp or replay protection.
  6. Make the handler safe to retry.
  7. Log event ID and request ID, not secrets or raw tokens.

Receiver Checklist

Step Requirement
Endpoint Use HTTPS in production.
Signing secret Keep it server-side and never expose it in browser code.
Signature verification Reject events before parsing trust-sensitive fields.
Timestamp check Limit replay windows.
Retry handling Make handlers idempotent and safe to run more than once.
Logging Log event ID and request ID, not raw secrets.

Event Handling Rules

  • respond quickly after verification
  • queue slow work
  • use idempotency keyed by event ID
  • treat unknown event types as safe no-ops or route them to review
  • rotate signing secrets with a deployment plan

For event names and payload reference, read Reference: Webhook Events.