> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcade.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Learn when a job finishes, without polling.

Arcade can send your server a signed request when a [job](https://docs.arcade.ai/jobs.md) finishes, so you don't have to poll. Polling with `jobs/get` keeps working.

## Events

| Type | Sent when |
| - | - |
| `job.succeeded` | A job succeeded. |
| `job.failed` | A job failed. |

A job from `patterns/create`, a refine, `products/create` or `products/generate` sends one event when it finishes. A `download` job sends none.

A product job's event can arrive about a minute after `jobs/get` reports the job finished.

Each request body is one event:

```json theme={null}
{
  "id": "019a4f5c-3c1e-7f3a-9a51-2f6e8d1b7c44",
  "type": "job.succeeded",
  "occurredAt": "2026-11-04T18:21:07.000Z",
  "data": {
    "jobId": "3583f242-50ed-4250-94c2-c00ea25249dd",
    "requestId": "my-request-1"
  }
}
```

| Field | Meaning |
| - | - |
| `id` | The event's ID. Use it to ignore duplicates. |
| `type` | `job.succeeded` or `job.failed`. |
| `occurredAt` | When the job finished. For a failed product job, when the failure was detected. |
| `data.jobId` | The job. |
| `data.requestId` | The `requestId` you sent in the call that started the job. |

An event carries IDs only. Call [`jobs/get`](https://docs.arcade.ai/api-reference/jobs/retrieve-a-job) with the `jobId` to read the job's result or error.

## Add a destination

1. In Arcade Studio, open **Settings → API keys** and select **Manage webhooks**. This opens the webhooks portal.
2. Add a destination with your HTTPS URL and the events you want.
3. Copy the destination's signing secret. It starts with `whsec_`.

Destinations belong to your account, not to one API key.

The portal also shows each delivery and your server's response, and lets you retry a failed delivery.

> [!NOTE]
>
> Open the portal before you start the jobs you want events for. A job started
> before you first opened it may not send an event.

## Test locally

Run the receiver below, then give it a public URL with a [quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/):

```bash theme={null}
cloudflared tunnel --url http://localhost:3000
```

Add the printed URL as a destination, with `/webhooks` on the end, then start a job with `patterns/create`.

## Verify the signature

Check the signature on every request, so you know it came from Arcade.

Each request has an `x-outpost-signature` header of the form `v0=<signature>`. To check it:

1. Compute the HMAC-SHA256 of the raw request body, using the whole signing secret as the key.
2. Encode the result as hex.
3. Compare it with the signature in the header.

Use the raw bytes of the body, before you parse the JSON. Parsing and serializing the body again can change it.

While you rotate a secret, the header holds two signatures separated by a comma. Accept the request if either one matches.

```javascript theme={null}
import crypto from 'node:crypto'
import express from 'express'

const seen = new Set() // Use your database in production.

const isSigned = (rawBody, header, secret) => {
  if (!header?.startsWith('v0=')) return false
  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex'),
  )
  return header
    .slice(3)
    .split(',')
    .some((candidate) => {
      const signature = Buffer.from(candidate)
      return (
        signature.length === expected.length &&
        crypto.timingSafeEqual(signature, expected)
      )
    })
}

const app = express()

app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('x-outpost-signature')
  if (!isSigned(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.sendStatus(401)
  }

  const event = JSON.parse(req.body)
  res.sendStatus(200)

  if (seen.has(event.id)) return
  seen.add(event.id)
  // Read the job with jobs/get using event.data.jobId.
})

app.listen(3000)
```

## Handle delivery

* **Respond quickly.** Return a `2xx` as soon as you have verified the request, and do your work afterwards. Any other response, or a timeout, counts as a failed delivery.
* **Expect retries.** A failed delivery is retried automatically, with a longer wait each time. Once the retries run out, you can retry it from the portal.
* **Ignore duplicates.** The same event can arrive more than once. Keep the `id` of each event you handle, and skip an `id` you have seen.
* **Don't rely on order.** Events can arrive in any order. Read the current state from the API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.