Receive a webhook
No API key is needed: the URL token authenticates requests.
No API key is needed: the URL token authenticates requests. Invalid tokens, absent triggers, wrong kinds and inactive time windows return 404; a paused trigger (circuit breaker after 5 consecutive failures, or manual pause) returns 409 TRIGGER_PAUSED whose message gives the reason and whose hint gives the way back, POST /automation/v1/triggers/{id}/resume. Raw bodies are limited to 512 KiB; serialized run input, including raw and parsed copies, must fit within 1 MiB. Exceeding either limit returns 413 synchronously without recording a firing; webhook-id deduplicates for 24 hours. A 202 with outcome=accepted acknowledges receipt; the final outcome is updated later, and repeats return deduped. Invalid JSON yields body=null; other UTF-8 is text and non-UTF-8 is base64. The envelope contains body, raw_body, raw_body_encoding, allowlisted headers, webhook_id and received_at. raw_body preserves exact bytes with utf8 or base64 encoding for caller-side signature verification.
POST /automation/v1/hooks/{trigger_id}/{token}
Authentication
Use the webhook URL returned on creation or rotation. The path token is the credential; no Bearer Key is required.
Request fields
| Parameter | Type | Description |
|---|---|---|
| path: trigger_id | string | required; Trigger ID (trg_). |
| path: token | string | required; Secret URL token returned on creation or rotation; do not disclose it. |
| header: webhook-id | string | optional; Optional deduplication identifier, retained for 24 hours within this trigger. |
application/json
Any JSON value: null, boolean, number, string, array or object.
| Field | Type | Description |
|---|---|---|
| (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
text/plain
string
application/octet-stream
string
Examples
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| TRIGGER_ID | Trigger id; resume before sending a webhook |
| WEBHOOK_TOKEN | Last segment of the new webhook_url; keep it private |
: "${TRIGGER_ID:?Set TRIGGER_ID}"
: "${WEBHOOK_TOKEN:?Set WEBHOOK_TOKEN}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/hooks/${TRIGGER_ID}/${WEBHOOK_TOKEN}" \
-H "Content-Type: application/json" \
--data '{
"n": 41
}'import { createAutomationClient } from '@deepraxis/sdk/automation';
function env(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name}`);
return value;
}
const automation = createAutomationClient({
apiKey: '',
baseUrl: 'https://api.deepraxis.ai',
maxRetries: 0,
timeoutMs: 90_000,
});
const result = await automation.hooks.send({
"path": {
"trigger_id": env("TRIGGER_ID"),
"token": env("WEBHOOK_TOKEN")
},
"body": {
"n": 41
}
});
console.log(result);Response
HTTP 202
Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Firing record id; records are kept for 30 days. |
| trigger_id | string | required; Id (trg_) of the trigger this firing belongs to. |
| scheduled_at | string | required; Planned firing time (RFC 3339 UTC); for webhooks, the time the request arrived. format: "date-time" |
| fired_at | string | required; Time the firing actually happened (RFC 3339 UTC). format: "date-time" |
| outcome | "accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped" | required; Firing outcome. accepted means persisted and awaiting processing; started means a run was created; skipped_overlap means skipped because the previous run was still active; missed means it was later than the catch-up window and was not run; failed means creating the run failed; deduped means it repeated a webhook-id seen within 24 hours. |
| run_id | string / null | required; Id (run_) of the run this firing created, or null if no run was created. |
| resolved_version | string / null | required; Exact version this firing resolved to; null when not yet resolved or when it failed before resolving. |
| error | object / null | required; Reason {code, message} when the firing failed; null otherwise. |
| error (variant 1).code | string | required; Error code of the failure. |
| error (variant 1).message | string | required; Message describing the failure. |
Measured response
HTTP 202
{
"id": "frg_00mv67n6in516077a64cfc4102a4da939476a3fa78",
"trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
"scheduled_at": "2026-10-13T04:58:18.384Z",
"fired_at": "2026-10-13T04:58:18.384Z",
"outcome": "accepted",
"run_id": null,
"resolved_version": null,
"error": null
}Errors
| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | TRIGGER_NOT_FOUND: The trigger does not exist or is inaccessible. Webhook authentication failures also use this code. |
| 405 | METHOD_NOT_ALLOWED: Only POST is supported; other methods return 405 before authentication with Allow: POST. |
| 409 | TRIGGER_PAUSED: The trigger is paused, either automatically by the circuit breaker after 5 consecutive firing failures or manually; the response message gives the reason and the hint gives the way back: resume the trigger (triggers.resume). |
| 412 | PRECONDITION_FAILED: The revision, source digest, or concurrent write precondition does not match. |
| 413 | PAYLOAD_TOO_LARGE: The request exceeds the size allowed for this operation. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.