Skip to main content
Orgo can push event notifications to a URL you control. Subscribe to any subset of 24 event types, register an HTTP(S) endpoint, and Orgo delivers a signed JSON POST every time a matching event happens. This page is the reference. For a complete walkthrough, including idempotent handling and replay, see Handle webhooks.

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 http and https, 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.
A refused address is rejected with 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 the object 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 a secret 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.
Respond 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.
This format shipped in August 2026 and replaced a short non-keyed checksum. There is no compatibility header: a receiver comparing the old value must move to the recipe above.

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 by payload["id"].
Keep delivery IDs for at least 30 days. If you can, insert the dedup row in the same transaction as the side effect. That closes a window where a crash mid-handler leaves the dedup row but not the effect.

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:
No body is needed. Orgo queues one delivery with the event type 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.