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

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Webhooks

> Signed HTTP callbacks for tool batches, incoming HTTP listeners, and monitoring alerts.

Cargo webhooks are signed HTTP callbacks. Cargo POSTs JSON to a URL you control when a batch finishes, when a monitored tool fails, or when an external system pushes an event into a model.

## Batch and tool completion

When you create a tool batch you may pass `webhookUrl` and, optionally, `webhookSecret`:

```bash theme={null}
curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches?token={your_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/cargo-callback",
    "webhookSecret": "your-secret",
    "data": [
      {"company_domain": "acme.com"}
    ]
  }'
```

`webhookUrl` is optional. When set, results are POSTed there on completion. When `webhookSecret` is set, Cargo signs every delivery with HMAC-SHA256 in the `X-Cargo-Signature` header (`sha256=<hex>`). Verify the signature before trusting a delivery:

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

function isValidSignature(rawBody: string, secret: string, header: string) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

See [Triggering a tool](/tools/triggering) for the rest of the batch API.

## Incoming HTTP listeners

The HTTP integration can **listen** for webhooks from an external system. Cargo issues a unique URL; a POST to that URL inserts or updates rows on a model and can enrol them in a play.

See [HTTP integration](/integration/http).

## Monitoring

Alerts and tool monitors can POST to your own systems on failure. See [Monitoring a tool](/tools/monitoring).