Documentation

Outbound webhooks

We POST to an address you own when a play reaches a verdict, a decision is taken, or an approval is waiting. Signed, replay-proof, ids and counts only.

We POST to an address you own when something in the loop happens: a play reached a verdict, somebody decided about a pattern, or an approval is waiting.

This is the opposite direction from a signal key. A signal key lets your system send us conversations; a webhook lets us tell your system what we found. Receiving events from us is never permission to act on your systems, and holding a signal key is never permission to receive these.

Add one under Settings › Where we reach you. The signing secret is shown once, when the webhook is created, and never again.

What we send

Five events. Pick the ones you want when you add the webhook.

EventWhen
resultA play's window closed and it reached a verdict.
decisionA pattern was closed, continued or reopened.
approvalSomething is waiting for a person to approve.
knowledgeA new version of a page, a snippet or an internal article was approved. For a team's own agent: the payload names the articleId, title, version (or null) and audience, and the agent fetches the text with the MCP server's get_knowledge, so it answers from exactly what a person approved.
playA play's step calls your own agent or system. Off unless ticked as Play steps; see [Play steps](#play-steps) below, because these are sent differently.

Every payload is ids, counts and titles. Conversation text, the body of anything awaiting approval, customer identifiers and access tokens never travel this way. The one exception is a play step that hands your agent words a person approved, exactly as approved (below). If you need the words, open the link the payload gives you, signed in.

Every payload carries the same four fields, plus the event's own:

{
  "id": "0a2c8a4e-6b1f-4f2a-9a7e-5f2d1c9b3e70",
  "event": "result",
  "occurredAt": "2026-09-15T02:14:07.918Z",
  "workspace": { "id": "8f1c2d3e-aaaa-bbbb-cccc-1234567890ab" }
}

Verifying a delivery

Two headers travel with every POST:

HeaderValue
X-SA-TimestampUnix seconds, as a string.
X-SA-Signaturesha256=<hex> of HMAC-SHA256 over ${timestamp}.${rawBody}.

The same shape Slack and Stripe use. Compare in constant time, and reject a timestamp more than five minutes from now — otherwise a captured delivery can be replayed at you forever.

A worked example, in Node:

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody, headers, secret) {
  const timestamp = headers['x-sa-timestamp']
  const signature = headers['x-sa-signature']
  if (!timestamp || !signature) return false

  // Refuse anything older than five minutes, so a captured POST cannot be replayed.
  const age = Math.abs(Date.now() - Number(timestamp) * 1000)
  if (!Number.isFinite(age) || age > 5 * 60_000) return false

  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const a = Buffer.from(expected)
  const b = Buffer.from(signature)
  return a.length === b.length && timingSafeEqual(a, b)
}

Sign over the raw body, before any JSON parsing: re-serializing changes the bytes and the signature will not match.

Retries, and what "delivered" means

Answer with any 2xx and quickly; we treat anything else as a failure and try again on a backoff, up to eight attempts, after which the delivery is dead and stays on its row for you to see under Settings › Where we reach you.

Never exactly-once. Each attempt is claimed before it is sent, so two of our runs never send the same delivery at once. But a timeout or a network failure after your server committed looks the same to us as one before, and we try it again, as we do an attempt that was cut off partway. So the same delivery can reach you more than once: make your handler idempotent on the payload's id, which is stable across every attempt of the same delivery.

A paused workspace sends nothing: deliveries are held, not dropped, and go when somebody resumes it. The demo workspace sends nothing at all, ever.

Choosing an address

https only. We refuse a URL with credentials in it, and in production we refuse addresses that resolve to obviously private hosts — a webhook pointed at localhost is a webhook that will never arrive, and saying so at the moment you paste it is better than a dead row a week later.

Play steps

For a team whose own agent or system should act on a play — update what its agent answers from, open a ticket in its own tracker, start its own work — a play can call the webhook. Tick Play steps on a webhook to let it; a webhook added for the other events is never called by a play. A plan names it as Tell your own agent or system or Hand your own agent the exact words to use, and both are offered only once a webhook takes play steps.

{
  "id": "5d0c3b8f9e2a41c7b6d4e1f0a9c8b7d6",
  "event": "play",
  "occurredAt": "2026-10-08T09:12:44.017Z",
  "workspace": { "id": "8f1c2d3e-aaaa-bbbb-cccc-1234567890ab" },
  "play": {
    "id": "c2b1…", "playbookId": "7e4f…", "patternId": null, "topicId": "41aa…",
    "title": "Refund window change", "url": "https://functioninghq.com/app/plays/c2b1…"
  },
  "step": { "key": "pb:7e4f…:1", "action": "webhook.notify", "title": "Tell our agent" },
  "revision": { "id": "93d0…", "hash": "a61f…" }
}

Hand your own agent the exact words adds words: the title, subject, body and language of the version a person approved — what your agent will tell customers, so the step runs only straight after a person approved those exact words, like the AI's own content, and the setting for it offers ask and off and nothing else. Nothing else a customer wrote travels, ever.

Delivered differently from the events above. A play step is an action, so it goes through the same gates as every play's send — a paused workspace or a failed payment holds it, a rate limit paces it — and it is claimed before it is sent:

  • a 2xx is sent, once;
  • a 4xx your server answered with is not sent, and the step says so;
  • a timeout, a dropped connection, a redirect or a 5xx after the request left is unknown: nothing is tried again, and the step waits for a person to look and say whether it arrived.

So it is at most once, or an explicit unknown — never retried on a backoff like the events above. The id is the same for every attempt of the same step, revision and webhook, so deduplicate on it if you ever see it twice. It is signed exactly like every other delivery.

Something missing, or a field that does not behave as this says? Tell us — the contracts here are what the code is held to, so a page that is wrong is a bug in the same sense the code would be.