Webhooks

A webhook endpoint (POST /webhooks) receives the public events of your account (the same ones returned by GET /events) as HTTPS POST requests, one event per request, signed with a signing secret specific to that endpoint. Delivery is at least once, so your receiver must be idempotent on the event id. Events are not guaranteed to arrive in order. Events caused by a sale, an import, or a delivery, such as user.created, enrollment.created, and user.tags_updated, can arrive a few minutes later than events for changes made in the dashboard or through the API. enrollment.updated is also sent when a sales platform suspends or reactivates an enrollment, through a cancellation, a refund, a chargeback, or a subscription renewal; a cancellation scheduled for a later date is sent when it takes effect.

For every field and parameter, see the Webhooks reference. For the event catalog, see Events. For the body of each event type, see the Webhooks v3 reference. To create and manage endpoints without the API, see Set up in the dashboard.

Registering an endpoint

• url must use https and point to a public host on port 443, 80, or 8443. URLs that point to private, loopback, link-local, or metadata addresses are rejected when you create or update the endpoint. The platform checks the resolved address again before every delivery, so a host that resolves to a non-public address makes the delivery fail.
• event_types[] lists the event types to subscribe to, taken from the catalog documented by GET /events. An endpoint created with API credentials receives events only while those credentials still have the events.read permission.
• resource_filters optionally narrows deliveries by resource. Each key is the resource type of an event type, as listed in the Resource column of the event catalog, such as product or lesson. Each value lists the IDs of that type to deliver, as public IDs (prd_7) or numeric IDs (7); IDs are returned in numeric form. An ID that does not belong to the resource type of its key returns 422 validation_failed. A filter applies only to events whose own resource is of that type, and event types whose resource type is not a key are delivered without restriction. null removes all filters.
  • lesson_progress.completed has the resource lesson, while product_progress.started, product_progress.completed, product_progress.milestone_reached, and product_progress.updated have the resource product. A product filter therefore does not restrict lesson_progress.completed: list the lessons under lesson to narrow it.
• event_filters optionally narrows deliveries further, by fields of the event data of each subscribed event type. See Filtering by event type.
• description is free text.
• payload_detail sets how much detail each delivery carries: ids (the default), masked, or full. See Payload detail level.
• The create response includes the secret (whsec_…) only once. It cannot be retrieved afterwards. POST /webhooks/{webhook_id}/secret-rotations generates a new signing secret and keeps the previous one valid for overlap_hours (24 by default, up to 72). During that period, each delivery carries one signature per active secret.
• timeout_ms (10,000 by default) and max_per_second (10 by default) are read-only through the API. GET /webhooks/{webhook_id} reports their current values. timeout_ms is the time limit of each request, applied between 1 and 10 seconds.
• status is active or inactive. Changing it with PATCH requires the webhooks.activate permission. Setting it to inactive pauses the endpoint: its pending deliveries wait and resume when you set it back to active, and events that occur while it is inactive are not queued for it. A paused delivery still becomes dead 72 hours after it was created. DELETE cancels pending deliveries; the delivery history is kept for the retention period. After DELETE, GET /webhooks/{webhook_id} returns 404, as the list leaves the endpoint out.

Payload and headers

Body: {"id": "evt_…", "type": "…", "version": 1, "occurred_at": "…", "data": {...}, "delivery_id": "whd_…", "attempt": n}. When the endpoint's payload_detail is masked or full, an expanded object follows data.

Headers: Cademi-Signature: t=<unix>,v1=<hex>[,v1=<hex>], Cademi-Signature-Version: 1, Cademi-Webhook-Id (whk_…), Cademi-Delivery-Id (whd_…), Cademi-Event-Type, User-Agent: Cademi-Webhooks/3, Content-Type: application/json.

Payload detail level

payload_detail applies to every event type the endpoint subscribes to. Set it with POST /webhooks or PATCH /webhooks/{webhook_id}; GET /webhooks and GET /webhooks/{webhook_id} return it. For the body you receive at each level, see PII payloads.

At every level, the reason an administrator writes in certificate.revoked and diamond_membership.stage_changed is sent as written.

expanded holds the resources the event refers to, such as user, product, or lesson, in the same format the API returns them. Products, lessons, and exams use the format of their listing operations: for a product, display and definitions are empty objects, and offer is not included. expanded is built when the delivery is created, so every attempt of a delivery sends the same objects. Every key of the event type is always present, and any of them can be null when the object is not available, for example because the resource was deleted: the event is still delivered, and you can fetch the resource from the API by its ID in data. An event type with no expandable resource sends expanded: {}. The Webhooks v3 reference lists the keys of expanded for each event type.

Masking rules

In masked, each personal field keeps its type and is masked by a fixed rule, so the same value is always masked the same way:

null stays null, empty text stays empty, a name made only of spaces is sent as is, an email without @ is masked as a user part only, and a document without digits becomes empty.

Masked personal data is still personal data: handle it as such. A masked value may not match the format declared for its field; for example, a masked email is not a valid address.

Permission for full

Setting payload_detail to full, or changing the event types of an endpoint whose payload_detail is full, requires the users.read_personal permission. It also requires tickets.read_personal when a subscribed event type expands a ticket (the ticket.* events), and legal_terms.read_proof when one expands a term_acceptance (term_acceptance.created). Without a permission the change requires, the request fails with 403 personal_data_permission_required, and nothing is created or changed. configuration.apply returns the same code on the affected item when a webhook in the plan needs a permission the current credentials do not have. The same rule applies when the endpoint is configured in the dashboard.

The permissions that keep full in effect are those of whoever created the endpoint: the API credentials or the dashboard administrator. Editing the endpoint later does not change this. When the creator loses one of the permissions full requires, new deliveries are sent as masked until the permission is restored. GET /webhooks/{webhook_id} returns the level new deliveries use in health.effective_payload_detail, which differs from payload_detail while this applies.

Deliveries already queued

Each delivery keeps the expanded object it was built with, and sends it only while the endpoint still accepts that level:

• If the level goes down, by PATCH or by the fallback to masked described above, queued deliveries built at a higher level are sent without expanded.
• If the level goes up, queued deliveries keep what they were built with: a delivery built at masked stays masked, and a delivery built at ids has no expanded.

GET /webhooks/{webhook_id}/deliveries and GET /webhooks/{webhook_id}/deliveries/{webhook_delivery_id} return in payload_detail the level each delivery was built at (ids when it has no expanded).

Every change of payload_detail, including creating an endpoint at masked or full, is recorded in GET /audit-entries with the action code webhook.payload_detail_changed and the previous and new level. The fallback to masked does not change payload_detail, so it is not recorded there; check health.effective_payload_detail instead.

Filtering by event type

event_filters narrows deliveries by fields of the event itself, on top of resource_filters. Set it with POST /webhooks, PATCH /webhooks/{webhook_id}, or the webhook kind of a configuration manifest; GET /webhooks and GET /webhooks/{webhook_id} return it, with every ID as a public ID, even when you sent it as a numeric ID.

Each key is one of the endpoint's event_types, and its value holds the filters for that type. An event is delivered only when it passes both resource_filters and every filter of its own event type; within a list, one match is enough. Event types without a key are delivered without these filters. null removes every filter, and an endpoint with no filters returns event_filters: null.

resource_filters and event_filters together

The two filters answer different questions:

• resource_filters looks only at the resource of the event, the Resource column of the event catalog. A key restricts only the event types whose own resource is of that type, and ignores the rest of the event.
• event_filters looks at the fields of one event type, such as the product of an exam attempt or the milestones reached.

An event is delivered only when it passes both. For example, an endpoint that subscribes to three event types:

{
  "event_types": ["exam_attempt.completed", "lesson_progress.completed", "product_progress.milestone_reached"],
  "resource_filters": { "product": ["prd_7"] },
  "event_filters": {
    "exam_attempt.completed": { "product_id": ["prd_7"], "passed": true },
    "product_progress.milestone_reached": { "milestones": [75, 90] }
  }
}

To narrow every event type to one product, use product_id in event_filters for each type that accepts it; resource_filters narrows only the events that are about the product itself.

Accepted filters

Only the event types below accept filters, each with a fixed set:

ID filters take a list of 1 to 200 IDs, as public IDs (prd_7) or numeric IDs (7), except legal_term_id, which takes public IDs only.

Example, an endpoint that receives only passing attempts of one exam and progress updates of one product at 50% or more:

{
  "url": "https://erp.example/hooks/cademi",
  "event_types": ["exam_attempt.completed", "product_progress.updated"],
  "event_filters": {
    "exam_attempt.completed": {"exam_id": ["exm_12"], "passed": true},
    "product_progress.updated": {"product_id": ["prd_7"], "min_percent": 50}
  }
}

The request fails with 422 validation_failed, and nothing is created or changed, when a key is not one of the endpoint's event_types or is an event type that does not accept filters, or when a filter is not accepted for its event type or has an invalid value. details[].field points to the event type or the filter, such as event_filters.exam_attempt.completed or event_filters.exam_attempt.completed.passed.

When you send event_filters in PATCH /webhooks/{webhook_id}, it replaces the previous value as a whole and is checked against the event_types the endpoint has after the change. A PATCH that changes event_types without sending event_filters drops the filters of the event types that were removed, so they do not return if you subscribe to those types again.

Test deliveries

"Send test" on the webhook endpoint page of the dashboard sends one event of a type you choose among those the endpoint subscribes to, with sample values in data and expanded, at the level new deliveries use (health.effective_payload_detail). It carries the same headers and is signed with the same active secrets as a real delivery, so you can confirm that your receiver accepts the request and verifies the signature before a real event occurs. You can send a test whatever the status of the endpoint, and the number of tests per endpoint is rate limited.

A test delivery adds test: true at the end of the envelope. Its occurred_at is the time of the test and its attempt is 1. Its id and delivery_id are new for every test and do not exist in the API: GET /events/{event_id} and GET /webhooks/{webhook_id}/deliveries/{webhook_delivery_id} return 404 not_found for them. A test delivery is sent once and never retried, is not listed among the deliveries of the endpoint, and does not count toward the circuit, health, or automatic deactivation. A real delivery never includes the test key. A test to a blocked destination is refused; when the DNS server does not answer for the host, the test reports a transport error, as a real delivery would.

Verify the signature of a test delivery the same way as any other delivery, described below. After that, either ignore it or use it to check that the shape of the event matches what your receiver expects; do not try to reconcile its id or delivery_id with the events or deliveries API.

Verifying the signature

t        = value of "t" in Cademi-Signature
expected = HMAC_SHA256(secret, t + "." + raw_body)   # lowercase hex
valid    = any "v1" in the header == expected (constant-time comparison)
           and |now - t| <= 300 seconds

Use the raw body exactly as received, without re-serializing the JSON. During a secret rotation, check every v1 in the header against the secret you hold; a single match is enough. See also Signatures.

The same verification code works during development with cademi listen --forward-to, which delivers events to a local URL with this body and these headers, signed with a local secret. Locally, Cademi-Webhook-Id is local and User-Agent identifies the CLI. See Event streams.

Responses and retries

The attempt field in the envelope counts every request sent to your endpoint, including the ones answered with 429 or Queue is full. Waiting for Retry-After, for a full queue, for the circuit, or for the host rate limit does not spend attempts, but the 72-hour limit still applies: a delivery that reaches it while waiting becomes dead.

Each request must complete within the timeout_ms of the webhook (1 to 10 seconds, 10 by default); the connection itself must be established within 5 seconds, or within timeout_ms if it is shorter. Redirects are not followed. A masked excerpt of the response body (response_excerpt, up to 4 KiB) is stored with the attempt for troubleshooting.

Circuit per URL

After three consecutive failed requests to the same URL (5xx, timeout, or connection error; a 429 does not count, and any other response resets the count), the platform opens a circuit for that URL. While the circuit is open, deliveries to that URL wait without spending attempts. After 5 minutes, a single test delivery goes out: if it fails, the circuit stays open for another 5 minutes; if the URL answers with anything other than a 5xx or a 429, the circuit closes and deliveries resume. The circuit belongs to the URL, so every webhook endpoint that points to it shares the same circuit, while endpoints that point to a different URL, even on the same host, keep receiving deliveries normally.

The request rate is limited per host, not per URL. When your endpoint answers 429, the platform lowers the rate for the whole host: to the value of the X-RateLimit-Limit or RateLimit-Limit header of the response, or to half the current rate when neither is present. The learned limit expires after 24 hours. Deliveries held back by the host rate limit wait without spending attempts.

GET /webhooks/{webhook_id} reports the circuit state in health.circuit_state: closed (delivering normally), open (deliveries wait), or half_open (a single test delivery is allowed).

Inspecting and resending deliveries

• GET /webhooks/{webhook_id}/deliveries, GET .../deliveries/{webhook_delivery_id}, GET .../attempts, and GET /webhooks/deliveries (across all webhook endpoints accessible with the current credentials) require the webhooks.deliveries.read permission.
• POST .../deliveries/{webhook_delivery_id}/attempts resends a delivery manually (same event id, new attempt number) and requires the webhooks.replay permission.
• POST /webhooks/{webhook_id}/replays creates a webhook.replay operation that resends retained events already delivered to this endpoint (selected by IDs, time range, or event types). It adds attempts to the existing deliveries and never creates new ones. Track the per-event results with GET /operations/{operation_id}. See Operations.
• GET /webhooks/{webhook_id} includes health for the last 24 hours: delivered, failed, dead, and pending counts, the last success and failure, consecutive failures, circuit_state, and effective_payload_detail.

Automatic deactivation

The platform deactivates a webhook endpoint when its deliveries keep failing: either 10 different deliveries of the endpoint fail within 24 hours, or its URL fails 30 times in a row. A server error, a connection failure, a timeout, a DNS server that does not answer, or a delivery that reaches the 72-hour limit while waiting counts toward these thresholds. A 4xx response, a 429, a Queue is full response, and a delivery that is only rescheduled do not. When the URL reaches 30 failures in a row, every endpoint that points to that URL is deactivated; endpoints with other URLs on the same host are not affected.

A deactivated endpoint shows status: inactive, its pending deliveries are canceled, and the administrators of the account are notified by email. PATCH /webhooks/{webhook_id} with status: active reactivates it: the circuit of its URL is reset, delivery resumes, and the deliveries from the last 48 hours that ended as dead or were canceled by the deactivation go back to the queue for a new attempt. Sending status: inactive to a deactivated endpoint does not change it.

Pausing an endpoint yourself with status: inactive is different: its pending deliveries wait instead of being canceled, and they resume when you set status back to active.

Retention and sandbox

Events are retained for 30 days. Webhook deliveries and their attempts are retained for at least 60 days after the delivery is created, and a delivery that has not reached a final status is kept. An event is removed only after its deliveries. In a sandbox account, deliveries to webhook endpoints registered in that sandbox are real, so you can use them as your test receiver, and every event generated in the sandbox is delivered to them, whatever its origin. See Sandbox.