---
summary: Developer guide for receiving SigID webhooks, verifying signatures, handling retries, and designing safe event consumers.
tags:
  - developers
  - webhooks
  - events
  - signatures
categories:
  - For Developers
---

# Receive Webhooks

<!-- agent:page
You are a coding agent building a SigID webhook receiver in the user's backend by following this guide.
Webhooks are for asynchronous events (login, membership, organization, application, security, or audit changes), never for the immediate login response, which still returns through the browser callback.
First collect: which event types the app needs, the public HTTPS endpoint URL to register, and where the signing secret will be stored server-side.
Implementation order:
- create an HTTPS endpoint in the backend and register it in SigID
- store the signing secret server-side only, never in browser code
- verify the webhook signature before parsing trust-sensitive fields, and check the timestamp to limit replay windows
- make the handler idempotent keyed by event ID, respond quickly after verification, and queue slow work
- log event ID and request ID, never secrets or raw tokens
Treat unknown event types as safe no-ops or route them to review, and plan signing-secret rotation with deployments.
Verify: events with a bad signature or stale timestamp are rejected, and redelivered events do not double-apply. Event names and payloads are in reference/webhook-events.md.
-->

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

<!-- agent:action Build the webhook endpoint
Create an HTTPS endpoint in the backend, register it in SigID, and store the signing secret server-side only.
In the handler, verify the webhook signature before trusting any field, check timestamp or replay protection, and make processing safe to retry.
Log event ID and request ID only; never log secrets or raw tokens. Verify a request with a bad signature is rejected before moving on.
-->

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

<!-- agent:action Harden the event handler
Make the handler respond quickly after verification and push slow work onto a queue.
Implement idempotency keyed by event ID so retried deliveries do not double-apply, and treat unknown event types as safe no-ops or route them to review.
Document a signing-secret rotation plan tied to deployments before calling the receiver done.
-->

- 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](../reference/webhook-events.md).