Skip to main content

Webhooks

identity-service can POST a signed JSON event to your URL when something happens in a company: a user is created, invited, or deleted, SCIM provisions someone, a group changes. Company owners and staff create webhook rules in Shellui admin, the admin API, or Django admin. Each rule maps one catalog event type (for example identity.user.created) to an HTTPS endpoint, such as an n8n workflow. Delivery is at-least-once, retried with backoff for up to 8 attempts.

How it works​

Business code calls emit_event(type, company, payload)
│
▼
Record the event in the event log (always, rule or not)
│
▼
Match enabled webhook ActionRule rows for that company + event type
│
▼
Insert ActionOutbox row(s) in the same DB transaction
│
▼
transaction.on_commit → best-effort delivery (timeout-bounded HTTP, off the request thread)
│
▼
DeliveryAttempt audit log; retries by the retry_webhooks scheduled job
  • The outbox lives in Postgres (or SQLite locally). Retries run every minute on the built-in scheduler, which uses Redis (REDIS_URL). See Scheduled jobs.
  • SCIM and API paths never block on slow external HTTP: delivery runs only after commit, with short webhook timeouts (default 5s).
  • Delivery is at-least-once; dedupe on the envelope id (same value as the webhook-id header).

Every event is also stored in the event log, shown in the admin panel under Log events and kept for the company data retention.

Magic link sign-in emails are not sent through webhook rules. identity-service always sends them itself, see Magic link.

Event catalog (identity.*)​

Event typeWhen it firesNotes
identity.scim.user.provisionedSCIM user create or re-enable (active: true)Company access only; not account creation
identity.scim.user.deprovisionedSCIM deprovision / active: falseDisables membership; user row remains
identity.user.createdFirst OAuth, SAML or magic link sign-in creates a User (including an invitee's first sign-in), or Django admin adds a user with company membershipCompany-scoped
identity.user.invitedPOST /api/v1/invitations (admin panel Invite user)No account exists yet: payload has invitation_id, email, language (invitation language), invited_by, invitation_url (app URL, not a credential), no user_id. While an enabled rule exists, identity-service skips its own invitation email
identity.user.invitation_revokedPOST /api/v1/invitations/{id}/revokeSame payload plus revoked_by. Sign-in with that email is refused until a new invitation
identity.user.deletedDjango admin deletes a User, DELETE /api/v1/users/{id} (admin panel), or DELETE /api/v1/user (self-service)Admin panel and self-service deletes emit for the current company only and keep accounts linked to other companies; Django admin emits once per membership before deleting the account
identity.user.updatedName, email, username, explicit avatar, language, region, company access, Django active flag, direct groups, or owner role changed via the API, Django admin, or SCIMPayload includes current values and changed_fields. Unchanged saves do not emit. No tokens or sign-in links. Same signing and retry as other webhooks
identity.group.createdSCIM or Django admin group create
identity.group.updatedDisplay name / external id change
identity.group.deletedGroup removed
identity.group.membership_changedSCIM group members add/remove/replace
identity.scim.token.createdAdmin REST or Django admin token createNo secret in payload
identity.scim.token.revokedToken revoke
identity.scim.provisioning_conflictSCIM 409 / displayName collisionTies to ScimProvisioningEvent
identity.auth.magic_link.requestedUser requested a passwordless email sign-in linkNotification only. Payload has request_id, email, expires_at, source and language, but never the sign-in link or token. Identity-service always sends the sign-in email itself, whether or not a rule exists

Sign-ins are recorded in the event log as identity.auth.login.succeeded and identity.auth.login.failed. They are log-only and cannot be used in webhook rules.

Envelope shape (webhooks)​

CloudEvents-inspired JSON:

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "identity.scim.user.provisioned",
"time": "2026-09-24T13:30:00+00:00",
"company": { "id": 1, "slug": "acme", "name": "Acme" },
"data": {
"user_id": 42,
"email": "ada@acme.com",
"username": "ada@acme.com",
"source": "scim",
"language": "en",
"region": "UTC"
}
}

Payloads never include secrets, bearer tokens, or password hashes.

Create a rule​

Create rules in Shellui admin, with the admin API, or in Django admin under Action rules. A rule has a company, an event type, a webhook URL, a signing secret, and an optional Authorization header.

Webhook config (stored JSON)​

{
"url": "https://your-n8n.example.com/webhook/abc",
"secret": "whsec_…",
"authorization_header": "Bearer optional-static-token"
}

Private and localhost webhooks: regular staff cannot turn on allow_private_urls for a rule. Only a superuser can, in Django admin, or operators set ACTIONS_WEBHOOK_ALLOW_PRIVATE=true for the whole deployment.

Webhook signing (Standard Webhooks style)​

Each POST includes:

HeaderMeaning
webhook-idSame as envelope id (stable across retries for one delivery)
webhook-timestampUnix seconds
webhook-signaturev1,<base64(hmac_sha256)>
X-Shellui-EventCatalog event type (for example identity.user.created)
X-Shellui-Delivery-AttemptAttempt number for this outbox row (1 on first try)
User-Agentshellui-identity-actions/1.0

Signed content: {webhook-id}.{webhook-timestamp}.{raw_body} (UTF-8), HMAC-SHA256 with your signing key.

JSON body: compact separators, keys sorted, UTF-8 (ensure_ascii=false). Verify signatures against the raw HTTP body, not a re-serialized JSON object.

Secrets: prefer Standard Webhooks form whsec_<base64> (identity decodes the suffix as the HMAC key). Plain string secrets still work for existing rules.

Step-by-step n8n setup: Using Shellui webhooks with n8n.

For replay protection, reject requests whose webhook-timestamp is more than a few minutes away from your clock (the examples use 5 minutes).

SSRF protections​

Before delivery, identity resolves the webhook hostname once, rejects private/link-local/reserved targets (unless private URLs are explicitly allowed), and opens the TCP connection to that resolved address while sending the original hostname in the Host header and TLS SNI.

Delivery, retries, and scheduling​

  • After commit, identity attempts delivery once in a background thread (5s default timeout via ACTIONS_WEBHOOK_TIMEOUT_SECONDS; errors never fail the user request).
  • Failed deliveries schedule next_attempt_at with exponential backoff: 30s * 2^(attempt-1), capped at 1 hour, unless 429 or 503 returns Retry-After (then the larger of backoff and Retry-After applies, still capped at 1 hour).
  • Up to ACTIONS_OUTBOX_MAX_ATTEMPTS (default 8), then status dead.
OutcomeRetry?
2xxNo (delivered)
404, 408, 409, 425, 429Yes (404 covers inactive n8n workflows)
400, 401, 403, 405, 410, 413, 422No (dead)
5xxYes
Timeouts, connection errorsYes
SSRF block (private URL not allowed)No (dead)
Disabled/deleted ruleNo (dead)

Each attempt is logged in Delivery attempts (HTTP status, error excerpt, duration) with a trigger: dispatch for the first try right after the event, automatic_retry for a try made by the retry_webhooks job. Django staff also see the scheduled_job_run_id of the run that made it. See Scheduled jobs monitoring.

The Docker image retries pending rows every minute with the retry_webhooks job, so there is nothing to schedule when REDIS_URL is set. To run it from your own scheduler instead, set SCHEDULER_ENABLED=false and run every minute:

python manage.py retry_webhooks --batch-size 50 --max-seconds 50 --concurrency 4

Keep --max-seconds below 60 so overlapping runs stay safe (skip-locked claims + lease).

Finished deliveries (delivered, dead) are deleted after the company data retention by purge_expired_data. See Scheduled jobs for both jobs.

Flags:

  • --batch-size (default 50)
  • --max-seconds (default 50)
  • --concurrency (default 4)
  • --dry-run (claim only, no HTTP)

Re-queue a dead row from Django admin or POST /api/v1/actions/deliveries/{id}/requeue.

Admin API​

Staff and company owners call these endpoints with an access token or a personal access token, plus the company_id query parameter, like the other admin endpoints.

MethodPathPurpose
GET/api/v1/actions/eventsEvent catalog with payload_fields and sample_envelope
GET/api/v1/actions/rulesList webhook rules (secrets redacted)
POST/api/v1/actions/rulesCreate a webhook rule
GET/api/v1/actions/rules/{id}Rule detail
PATCH/api/v1/actions/rules/{id}Update fields or config
DELETE/api/v1/actions/rules/{id}Delete a rule
POST/api/v1/actions/rules/{id}/send-testPOST a sample envelope to the rule URL (no outbox row)
POST/api/v1/actions/rules/{id}/rotate-secretGenerate a new whsec_ signing secret (returned once)
GET/api/v1/actions/deliveriesPaginated delivery log. Staff can filter by scheduled_job_run_id
GET/api/v1/actions/deliveries/{id}Delivery detail with envelope and attempts
POST/api/v1/actions/deliveries/{id}/requeueRe-queue a row

Example: create a webhook rule​

Omit secret (or send a blank value) to auto-generate a Standard Webhooks secret (whsec_…). The create response matches rule GET plus top-level secret with the stored plaintext (generated or client-provided). List, GET, and PATCH never include top-level secret.

POST /api/v1/actions/rules?company_id=1
{
"name": "n8n user hook",
"event_type": "identity.user.created",
"url": "https://n8n.example.com/webhook/abc"
}

Example 201 body (same fields as GET /rules/{id}, plus secret):

{
"id": 1,
"company_id": 1,
"name": "n8n user hook",
"event_type": "identity.user.created",
"enabled": true,
"action_kind": "webhook",
"secret": "whsec_…",
"config": {
"url": "https://n8n.example.com/webhook/abc",
"has_secret": true,
"secret_hint": "abcd",
"authorization_header_set": false
},
"created_at": "…",
"updated_at": "…"
}

Rotate signing secret​

POST /api/v1/actions/rules/1/rotate-secret?company_id=1

200 response uses the same flat shape as create and GET, with a new top-level secret (update n8n before the next delivery):

{
"id": 1,
"company_id": 1,
"name": "n8n user hook",
"event_type": "identity.user.created",
"enabled": true,
"action_kind": "webhook",
"secret": "whsec_…",
"config": {
"url": "https://n8n.example.com/webhook/abc",
"has_secret": true,
"secret_hint": "wxyz",
"authorization_header_set": false
},
"created_at": "…",
"updated_at": "…"
}

List, detail, and update responses never include top-level secret. Webhook config includes has_secret, optional secret_hint (last four characters), and authorization_header_set instead of plaintext values.

Email rules, email template endpoints, and email_context_fields on the events catalog were removed. Company emails for catalog events go through email-service instead, see Email delivery. An enabled webhook rule on identity.user.invited still replaces the built-in invitation email; a rule on identity.auth.magic_link.requested does not.

Adding a new event type (developers)​

  1. Register the type in apps/actions/identity_events.py. List payload keys that are live credentials in sensitive_fields so they are never written to the event log, and set webhook=False for log-only events.
  2. Call emit_event(...) or emit_event_if_rules(...) from the business path inside a transaction when appropriate.
  3. Document the payload in this file and add tests under apps/actions/tests/.

To copy this pattern to storage-service or hosting-service, reuse the self-contained modules under apps/actions/ (emit.py, event_log.py, retention.py, delivery.py, handlers/webhook.py, webhook_signing.py, webhook_transport.py, ssrf.py, management/commands/retry_webhooks.py, management/commands/purge_expired_data.py, tasks.py, models, and admin API views, plus config/celery.py and config/task_lock.py for the scheduler), register service-specific events, and wire emit_event from domain code.