Docs
siDiscord

Webhooks

A service takes events from senders that push, at a URL per tool, verified with Standard Webhooks before anything runs.

A webhook is a POST a sender makes when something happens. How a service takes one in code: Webhooks in code.

Connecting a sender

  1. Deploy a service with a #[tool(webhook)] tool.
  2. Give the sender this URL:
https://api.crabtalk.ai/services/<owner>/<service>/webhooks/<tool>
  1. Set the signing secret the sender gives you. A person sets it, as with any secret:
printf %s "$VALUE" | crab secret put <service> WEBHOOK_SECRET

What is verified

  • Each webhook carries webhook-id, webhook-timestamp and webhook-signature, as Standard Webhooks specifies.
  • The signature must match the body under WEBHOOK_SECRET, base64 with an optional whsec_ prefix, and the timestamp must be within 5 minutes of now.
  • One that fails is refused before it reaches the service, and uses nothing.
  • Cloud opens WEBHOOK_SECRET to verify webhooks and never sends it to the node or the service.
  • A sender with its own signing scheme, such as GitHub's X-Hub-Signature-256, can't call this route.

What the sender gets back

Status Means
204 The tool ran.
400 Signature headers are missing or malformed (E0016), or the timestamp is stale (E0017).
401 The signature doesn't match (E0017).
404 No such service or webhook tool (E0014), or no usable secret (E0015).
413 The body exceeds Cloud's 2 MiB limit.
429 An IP or destination-service rate/concurrency limit was reached, with Retry-After; or the account holds as much memory as it may (E0019).
500 The tool failed, with its message.
503 The service is stopped or its account is held (E0018).

See Request limits for shared webhook quotas and retry responses.

Running them

A webhook is a run paid by the service's owner, and shows in crab calls with the source webhook. Its output isn't sent back to the sender.

On the local host, crab dev takes a webhook at /services/local/<service>/tools/<tool>/webhook without checking a signature.