> For the complete documentation index, see [llms.txt](https://docs.usedecentral.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usedecentral.org/api-reference/webhooks.md). # Webhooks Decentral can deliver real-time event notifications to an HTTPS endpoint of your choosing. Webhooks are useful for responding to job completions without polling the Jobs API, monitoring credit levels, and triggering downstream workflows. *** ## Configuring a webhook Create and manage webhooks in the Settings tab at `usedecentral.org/app/settings`. You can also configure webhooks programmatically: ```bash curl -X POST https://api.usedecentral.org/v1/webhooks \ -H "Authorization: Bearer dcntrl_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/decentral-events", "events": ["job.completed", "credit.low"], "secret": "your_signing_secret" }' ``` ```json { "id": "wh_9ax3mb5n7kqrstvwxyz", "url": "https://your-server.com/decentral-events", "events": ["job.completed", "credit.low"], "created_at": "2026-06-15T09:00:00Z", "status": "active" } ``` The `secret` is used to sign webhook deliveries. Store it securely; it is shown only at creation time. *** ## Event types | Event | When it fires | | ------------------- | ---------------------------------------------------------------- | | `job.submitted` | A job has been created and credits locked in escrow | | `job.processing` | A worker has acknowledged the job and inference has started | | `job.completed` | The job has settled on-chain and the worker has been paid | | `job.failed` | The job failed before completion (routing error, worker dropped) | | `job.timeout` | No worker completed the job within 120 seconds; credits refunded | | `job.disputed` | A dispute was opened on a completed job | | `credit.low` | Your credit balance has dropped below the configured threshold | | `credit.topup` | Credits were added to your balance | | `worker.registered` | A new worker registered (provider-facing) | | `worker.slashed` | A worker had stake slashed due to a confirmed fraudulent proof | Subscribe to only the events you need. The `events` array accepts any combination. *** ## Event payload format All events share a common envelope: ```json { "id": "evt_7bx2ma4n6jpqruvwxyz", "event": "job.completed", "created_at": "2026-06-15T14:22:03Z", "api_version": "2026-06-01", "data": { ... } } ``` ### `job.completed` ```json { "id": "evt_7bx2ma4n6jpqruvwxyz", "event": "job.completed", "created_at": "2026-06-15T14:22:03Z", "api_version": "2026-06-01", "data": { "job_id": "job_8fx2kp3m9qrstvwxyz", "model": "qwen3-8b", "tier": "standard", "credits_charged": 8, "usdc_value": 0.08, "worker_address": "9WzDXwBcARV1LCkUjzAt7skwM3Qe7rMDDkSmXbkw4KKD", "settlement_tx": "7mNPqRTvwXyz3ABCdEfGhIjKlMnOpQrStUvW4xKTgFZb", "solana_slot": 321847293, "prompt_tokens": 48, "completion_tokens": 214, "credits_remaining": 1412 } } ``` ### `credit.low` ```json { "id": "evt_3cx1la5n7kqrtvwxyz", "event": "credit.low", "created_at": "2026-06-15T15:00:00Z", "api_version": "2026-06-01", "data": { "credits_remaining": 87, "usdc_value": 0.87, "threshold": 100 } } ``` The `credit.low` threshold can be configured in Settings. Default is 100 credits. ### `worker.slashed` ```json { "id": "evt_5dx4nb8m2lqruvwxyz", "event": "worker.slashed", "created_at": "2026-06-15T16:00:00Z", "api_version": "2026-06-01", "data": { "worker_address": "9WzDXwBcARV1LCkUjzAt7skwM3Qe7rMDDkSmXbkw4KKD", "slash_amount_dcntrl": 500, "slash_tx": "2BCdEfGhIjKlMnOpQrStUvW4xKTgFZb7mNPqRTvwXyz9A", "reason": "fraudulent_proof", "related_job_id": "job_2ax1jb4k8npqruvwxyz" } } ``` *** ## Verifying webhook signatures Every webhook delivery includes a `Decentral-Signature` header. Verify it to confirm the request came from Decentral and was not tampered with. **Signature format:** ``` Decentral-Signature: t=1750000000,v1=a1b2c3d4e5f6... ``` * `t` is the Unix timestamp of delivery * `v1` is the HMAC-SHA256 of `{timestamp}.{raw_request_body}` using your webhook secret **Verification in Node.js:** ```typescript import crypto from "crypto" function verifyWebhook( rawBody: string, signature: string, secret: string ): boolean { const [tPart, v1Part] = signature.split(",") const timestamp = tPart.replace("t=", "") const receivedSig = v1Part.replace("v1=", "") const payload = `${timestamp}.${rawBody}` const expected = crypto .createHmac("sha256", secret) .update(payload) .digest("hex") return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(receivedSig) ) } // In your webhook handler: app.post("/decentral-events", express.raw({ type: "application/json" }), (req, res) => { const sig = req.headers["decentral-signature"] as string const isValid = verifyWebhook(req.body.toString(), sig, process.env.WEBHOOK_SECRET!) if (!isValid) { return res.status(400).json({ error: "Invalid signature" }) } const event = JSON.parse(req.body.toString()) // Handle event... res.json({ received: true }) }) ``` **Verification in Python:** ```python import hmac import hashlib def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool: parts = dict(p.split("=", 1) for p in signature.split(",")) timestamp = parts["t"] received_sig = parts["v1"] payload = f"{timestamp}.{raw_body.decode()}" expected = hmac.new( secret.encode(), payload.encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, received_sig) ``` Always use a constant-time comparison (`timingSafeEqual` / `hmac.compare_digest`) to prevent timing attacks. *** ## Retry behavior If your endpoint returns a non-2xx status code or does not respond within 10 seconds, the delivery is retried with exponential backoff: | Attempt | Delay | | ------- | ---------- | | 1 | Immediate | | 2 | 30 seconds | | 3 | 5 minutes | | 4 | 30 minutes | | 5 | 2 hours | After five failed attempts, the webhook is marked as failed and no further retries are made. You can view failed deliveries and replay them from the Settings tab. *** ## Managing webhooks List webhooks: ```bash curl https://api.usedecentral.org/v1/webhooks \ -H "Authorization: Bearer dcntrl_live_your_key_here" ``` Delete a webhook: ```bash curl -X DELETE https://api.usedecentral.org/v1/webhooks/wh_9ax3mb5n7kqrstvwxyz \ -H "Authorization: Bearer dcntrl_live_your_key_here" ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.usedecentral.org/api-reference/webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.