# Webhooks

> Get notified about deploys and budgets at your own endpoint.

Register an HTTPS endpoint under **Webhooks** in the console (or `POST /client/webhooks`) and Roar will notify it when things happen.

## Events

| Event | Fired when |
| --- | --- |
| `deploy.succeeded` | A hosted app finished deploying |
| `deploy.failed` | A deploy didn't finish (previous version stays live) |
| `budget.alerting` | A budget crossed its warning threshold |
| `budget.exceeded` | A budget is used up |
| `ping` | You pressed "Send test" |

## Verifying deliveries

Each webhook has a signing secret (`whsec_…`, shown once at creation). Every delivery is signed:

| Header | Value |
| --- | --- |
| `x-roar-event` | The event type |
| `x-roar-delivery` | Unique delivery id (deduplicate on this) |
| `x-roar-signature` | `sha256=` + HMAC-SHA256 hex of the raw body |

<CodeCard caption="Node.js verification">

```js
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    createHmac("sha256", secret).update(rawBody).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}
```

</CodeCard>

## Retries

Non-2xx responses (and timeouts) are retried with exponential backoff for up to six attempts. Handlers should be idempotent — deduplicate on `x-roar-delivery`.