Hosting webhooks
Company owners and staff can POST a signed JSON body to an HTTPS endpoint when a hosting event happens. Each Shellui Actions rule maps one catalog event, such as hosting.deployment.succeeded, to one webhook URL.
hosting-service delivers those webhooks itself. There is no central actions service and no message bus. When EMAIL_SERVICE_API_KEY is set, the same event is also forwarded to email-service. That forward is not a webhook rule. See Email notifications.
How a delivery runs
Domain code calls emit_event inside the database transaction that changed the app or deployment:
- The event is written to the event log, whether or not a rule matches.
- Each enabled webhook rule for that company and event type gets an outbox row in the same transaction.
- After commit, a background thread POSTs the envelope. The API response does not wait for your server.
- Each try is stored as a delivery attempt. Further tries come from
manage.py retry_webhooks.
The first POST runs in a background thread after commit. Later attempts are the scheduled job in Scheduled jobs. The default HTTP timeout is 5s (ACTIONS_WEBHOOK_TIMEOUT_SECONDS). Delivery is at-least-once. Retries reuse the envelope id, which is also the webhook-id header. Dedupe on that value.
The n8n setup, including a signature check, is in n8n. The retry schedule is in Scheduled jobs.
Event catalog
| Event type | When it fires |
|---|---|
hosting.app.created | A hosted app row is created |
hosting.app.deleted | A hosted app and its deployments are removed |
hosting.deployment.created | A deployment row is created and waiting for an upload |
hosting.deployment.succeeded | Finalize finished and the deployment is active |
hosting.deployment.failed | Extract failed during finalize |
The body is UTF-8 JSON with non-ASCII characters left as characters (ensure_ascii=false). Verify the signature over the raw body bytes, not over a re-serialized object.
Extra headers: X-Shellui-Event, X-Shellui-Delivery-Attempt. Signing secrets are plain text or Standard Webhooks whsec_ plus base64. Shellui decodes the whsec_ suffix and uses those bytes as the HMAC key.
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "hosting.deployment.succeeded",
"time": "2026-09-24T13:30:00+00:00",
"company": { "id": 1 },
"data": {
"app_id": "550e8400-e29b-41d4-a716-446655440000",
"deployment_id": "660e8400-e29b-41d4-a716-446655440001",
"status": "active"
}
}
The id values above are samples. A real delivery uses a new id, and the same id again on every retry of that delivery.
Admin API
Paths match identity-service. Authorize with a Bearer JWT. Staff may pass any company_id query parameter. Company owners are limited to the company_id claim. They may omit the parameter or repeat their own id. Another company returns 403.
GET /api/v1/actions/events: catalog, including asample_envelopefor each typeGETandPOST /api/v1/actions/rules: list or create webhook rules. Create returnssecretonce when one was generatedGET,PATCH, andDELETE /api/v1/actions/rules/{id}POST /api/v1/actions/rules/{id}/rotate-secret: new signing secret, returned oncePOST /api/v1/actions/rules/{id}/send-testGET /api/v1/actions/deliveries: paginated delivery logGET /api/v1/actions/deliveries/{uuid}: one delivery and its attemptsPOST /api/v1/actions/deliveries/{uuid}/requeue
Later reads of a rule expose has_secret and secret_hint (the last four characters), not the secret.
Retries
Backoff is 30s * 2^(n-1), capped at 1 hour, with at most 8 attempts (ACTIONS_OUTBOX_MAX_ATTEMPTS).
| Result | Retry? |
|---|---|
| 2xx | No. The delivery is delivered |
| 404, 408, 409, 425, 429 | Yes. 404 covers an inactive n8n workflow |
| 400, 401, 403, 405, 410, 413, 422 | No. The delivery is dead |
| Other 4xx | Yes |
| 5xx, timeouts, connection errors | Yes |
429 or 503 with Retry-After | Yes. The delay is the larger of the backoff and Retry-After, still capped at 1 hour |
python manage.py retry_webhooks --batch-size 50 --max-seconds 50 --concurrency 4
The container runs that command every minute. Delivered and dead deliveries are deleted after EVENT_LOG_RETENTION_DAYS by purge_expired_data. See Scheduled jobs.
Webhook URLs that resolve to a private or loopback address are blocked unless the rule has allow private URLs (staff) or ACTIONS_WEBHOOK_ALLOW_PRIVATE is true. When that variable is unset, it follows DEBUG.