Available events
Every event ships with the entity snapshot (
object) and, for updates, a diff (previous_attributes). The OpenAPI spec declares a typed payload schema for the first 18 events (the six families above the badge rows). The badge and badge-step events share the same envelope but have no typed schema yet.
Subscribing
An Orgo administrator creates a subscription in the admin UI under Settings → Developers → Webhooks, or with the API:
The
secret is yours to choose: a 32-byte random string is standard. Orgo uses it to sign each delivery so you can verify the payload came from Orgo. The response includes the subscription id, counters (totalDeliveries, successfulDeliveries, failedDeliveries) and lastTriggeredAt.
Managing subscriptions (create, list, update, delete, test, read logs) requires an Orgo administrator.
Where deliveries can go
The URL is checked when you save it and again at every delivery:- Only
httpandhttps, on the standard ports 80 and 443, and with no credentials in the address. - The host must resolve to a public address. Private ranges, loopback, link-local and cloud-metadata addresses are refused.
- A redirect is followed only to another address that passes the same checks, and only a few times.
422 when you save, and a delivery to an address that later stops qualifying is logged as failed and not retried.
Payload envelope
Every delivery, regardless of event type, has the same outer shape (Stripe-inspired). Only theobject and previous_attributes differ per event.
The OpenAPI spec declares a
Webhook.<EventName> schema for the first 18 event types (for example Webhook.UserCreated). Use these in your typed client for autocomplete and validation.
Delivery headers
Headers you configured in
headers are added to these.
Authenticating the sender
Set asecret on the subscription and every delivery carries X-Webhook-Signature in this shape:
The timestamp is inside the signed string, so it cannot be edited without invalidating
v1. That is what lets you reject a captured delivery replayed later. A subscription with no secret sends no X-Webhook-Signature header at all.
Verify against the raw body. A body that has been parsed and re-serialized is a different byte string and will not match.
401 and log the delivery ID when verification fails. Orgo treats that as a failed delivery and retries it, which is the behavior you want if the failure is your own misconfiguration.
Each retry is signed at the moment it is sent, so the same delivery ID can arrive with different t and v1 values. Deduplicate on the payload id or X-Webhook-Delivery, never on the signature.
Idempotency
Orgo may deliver the same event twice: retries after a slow response, or network races on at-least-once delivery. Your handler must be safe to call repeatedly with the same payload. The simplest pattern: track processed deliveries bypayload["id"].
Retry behavior
maxRetries is the maximum number of attempts for one delivery. With the default of 3, Orgo calls your endpoint at most three times: the second attempt comes 20 seconds after the first failure and the third 40 seconds after the second. The delay doubles with each attempt (20, 40, 80 seconds, …) up to 10 minutes. Setting it to 0 or 1 disables retries.
The subscription itself is not deactivated on repeated failures. Watch failedDeliveries on the subscription, or your own error rate.
Delivery logs and replay
Every delivery attempt, success or failure, is logged with the request payload, your response status and body, and the time taken. To list the most recent ones:limit defaults to 100 and is capped at 500. The original payload is stored with each log, so you can replay a failed delivery locally without waiting for Orgo to send it again. Do not rely on the log as a long-term archive: take what you need promptly.
Testing
Before going live, send a synthetic event to your endpoint:webhook.test and answers immediately with {"success": true, "message": "Test webhook dispatched successfully", "delivery_id": "..."}. The delivery itself is asynchronous, so look at your endpoint or at the delivery logs for the result. The test payload describes the subscription (name, url, event_types, is_active) rather than a member, and it carries the same headers and signature your handler sees in production. It is not an example of any real event’s object.
Webhook events
Each of the first 18 event types is declared as a “webhook” in the OpenAPI spec, which Mintlify renders in the playground under a Webhooks section. Open an event to see its full payload schema and example. All 24 event types are listed at the top of this page.Related
- Handle webhooks: full receiver walkthrough with idempotency and replay
- Sync your CRM with Orgo: webhooks in a real-world sync scenario
- Rate limits: why webhooks beat polling

