Cargo webhooks

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:

curl -X POST "https://api.getcargo.io/v1/tools/{tool_id}/batches" \
  -H "Authorization: Bearer $CARGO_API_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:

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);
}

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. Typical sources: form submissions, payment notifications, CRM events, Zapier or Make.

See https://docs.getcargo.ai/integration/http.

Monitoring

Alerts and tool monitors can POST to your own systems on failure. The payload names the run, the tool or play, and the error. Configure these from the CLI or the console; see https://docs.getcargo.ai/tools/monitoring.

Related

• Cargo API docs
• Triggering a tool, including the batch webhook fields: https://docs.getcargo.ai/tools/triggering