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

# Customer webhooks

> Events OneShot posts to your HTTPS endpoints, delivery and retries, signature checks, and minimal bodies for private-storage organizations

OneShot posts signed JSON to your URL for case results, goal notices, inbound calls and watch changes. Destinations must be public HTTPS.

## Events

| Event | Set the URL | Secret | Dedupe on | Details |
| - | - | - | - | - |
| `case.result` | `params.result_webhook_url`, or one `webhook` in a goal spec's `deliver` | `GET /v1/compute/{goalId}/result-webhook` | `delivery_id` | [Results](https://docs.oneshotagent.com/api-reference/compute/events.md#results-out) |
| Goal notices: `goal.awaiting_budget`, `goal.budget_warning`, `goal.awaiting_connection`, `goal.awaiting_setup`, `goal.awaiting_tool` | The goal's `result_webhook_url` | Same as `case.result` | `delivery_id` | [Budget](https://docs.oneshotagent.com/api-reference/compute/budget.md), [holds](https://docs.oneshotagent.com/api-reference/compute/status.md#connection-holds), [tool holds](https://docs.oneshotagent.com/api-reference/compute/cancel.md#tool-holds) |
| `voice.inbound.completed` | `webhook_url` in `PUT /v1/tools/voice/numbers/{id}/inbound` | `webhook_secret`, returned once when the URL is set or changed | `call.id` | [Inbound voice](https://docs.oneshotagent.com/api-reference/voice/inbound.md#webhook) |
| `watch.change` | `webhook_url` when you create or change a watch | `webhook_secret`, returned once; a new URL gets a new secret | `delivery_id` | [Watches](https://docs.oneshotagent.com/api-reference/watch.md) |

Results and goal notices name the event in `event`, voice and watch events in `type`. Goal notices carry `goal_id`, `status`, `message` and hold fields.

```json theme={null}
{
  "event": "case.result",
  "goal_id": "<goal ID>",
  "case": "SHIPMENT-8841",
  "session_id": "<session ID>",
  "result": { "amount_usd": 1180 },
  "approval": { "ask_id": "<ask ID>", "who": "Rae", "when": "2026-11-08T12:00:00.000Z", "via": "link" },
  "delivery_id": "<delivery ID>",
  "attempt": 1
}
```

## Delivery

* A `2xx` answer delivers. Anything else fails the attempt, including a redirect, which is never followed. The response body is ignored. An attempt times out after 5 seconds.
* The URL must use `https`, have at most 2,048 characters and no credentials, and its host and every address it resolves to must be public. It is checked when set and on every attempt.
* `case.result`: up to 6 attempts, 2, 4, 8, 16 and 32 minutes apart. `GET /v1/compute/{goalId}/cases/{key}` lists each in `deliveries` with `status`, `attempts`, `last_error` and `next_attempt_at`. A case that asked for approval sends only the result its approver released.
* Goal notices: up to 6 attempts on the same schedule. A hold notice stops when the hold ends. `goal.budget_warning` is sent when spend crosses `alert_threshold`.
* `watch.change`: up to 6 attempts over about 15 hours. `GET /v1/org/watches/{id}/deliveries` shows `webhook_status`, `webhook_attempts` and `webhook_last_error`.
* `voice.inbound.completed`: one attempt. The call stays in `GET /v1/tools/voice/inbound`.
* Events can arrive out of order or twice. Drop repeats by the dedupe key.

## Verify a signature

`X-OneShot-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. Each attempt is signed again with a new `t`.

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

// rawBody: the request bytes as received, before any JSON parsing.
export function verifyOneShot(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
  if (!/^\d+$/.test(parts.t ?? "") || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false; // older than 5 minutes
  const expected = createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest();
  return timingSafeEqual(Buffer.from(parts.v1, "hex"), expected);
}

// Express: app.post("/hooks", express.raw({ type: "application/json" }), (req, res) =>
//   verifyOneShot(req.body, req.get("X-OneShot-Signature") ?? "", secret) ? res.sendStatus(204) : res.sendStatus(401));
```

## Private-storage organizations

When an organization's controls require private storage, or cannot be read, each attempt sends a minimal body: IDs, status, timestamps and an `api_path`. Content, the event label and the attempt count are left out.

```json theme={null}
{
  "goal_id": "<goal ID>",
  "delivery_id": "<delivery ID>",
  "session_id": "<session ID>",
  "status": "pending",
  "created_at": "2026-11-08T12:00:00.000Z",
  "api_path": "/v1/compute/<goal ID>/deliveries/<delivery ID>"
}
```

| Event | Fields | `api_path` |
| - | - | - |
| `case.result` | `goal_id`, `delivery_id`, `session_id`, `status`, `created_at` | `/v1/compute/{goalId}/deliveries/{deliveryId}`: the stored event in `data.payload` |
| Goal notices | `goal_id`, `delivery_id`, `status`, `created_at` | `/v1/compute/{goalId}` |
| `voice.inbound.completed` | `call_id`, `receipt_id`, `status` (`ended` or `declined`) | `/v1/tools/voice/inbound/{callId}` |
| `watch.change` | `watch_id`, `delivery_id`, `notification_id`, `receipt_id`, `status` (`changed`) | `/v1/tools/notifications?id={notificationId}` |

Read `api_path` with your normal API credentials. The webhook secret does not authorize reads.


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