FlowmageDocs
Developers

Webhooks

What a system sends to a Flowmage webhook, what it gets back, and what the flow receives: method, headers, keys, signatures, status codes and the trigger payload.

To make a webhook, see Start a flow from a webhook.

curl
curl -X POST 'https://hooks.flowmage.com/hook/whu_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Anna","email":"anna@example.com"}'
JavaScript
const response = await fetch("https://hooks.flowmage.com/hook/whu_YOUR_TOKEN", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name":"Anna","email":"anna@example.com"}),
});
console.log(response.status, await response.text());
Python
import requests

response = requests.post(
    'https://hooks.flowmage.com/hook/whu_YOUR_TOKEN',
    headers={
        'Content-Type': 'application/json',
    },
    data='{"name":"Anna","email":"anna@example.com"}'.encode(),
)
print(response.status_code, response.text)

What you send

PartWhat a webhook takesNotes
MethodPOSTAny other method gets 404.
URLhttps://hooks.flowmage.com/hook/whu_…On the webhook's page in Triggers.
KeyAuthorization: Bearer <key>, x-api-key: <key> or ?key=<key>Only when the webhook has a Sender key.
Request ididempotency-key: <id>Or x-idempotency-key, x-request-id, x-github-delivery. The same id again, within the window the builder above shows, starts no second run.
Contentcontent-type: application/json and a JSON documentAny other content arrives as text, in trigger.body.rawBody.
Signaturex-hub-signature-256: sha256=<hex> (GitHub) or the Signature header you set, x-signature at first (Generic HMAC-SHA256)Only when the webhook has a Signature check: the HMAC-SHA256 of the raw request, made with its Signing secret.

What Flowmage answers

StatusWhenWhat it sends back
202The webhook took the request and started the run.{"executionId":"…"}; with two or more flows on it, {"executions":[…],"deliveryIds":[…]}
200Answer the caller is on; the run finished.What Answer with works out, or the last node's output.
500Answer the caller is on; the run failed.{"error":{"code":"…","message":"…"},"executionId":"…"}
504Answer the caller is on; the run took longer than Wait at most and goes on.{"executionId":"…"}
404The URL is unknown, no flow on it is published in the webhook's environment, or the key is missing or wrong.Not found
401The signature is missing or does not match.Not found
403The sender's address is not under Allowed addresses.{"error":{…}}
413The request is larger than a webhook takes.{"error":{…}}
429Over Deliveries per minute, or over a workspace limit.{"error":{…}}, and a Retry-After header

What the flow receives

In the flowHolds
trigger.bodyThe JSON you sent.
trigger.headersThe headers, by name.
trigger.queryThe query parameters, by name.
trigger.methodPOST
trigger.receivedAtWhen it arrived, as an ISO 8601 time.
trigger.fileWhat was sent, when larger than the size on Limits, kept as a file in place of trigger.body.

How they behave

  • Credentials stay out of the run. authorization, x-api-key and every header with signature or hmac in its name arrive as •••, as does a key query parameter. Cookies are left out.
  • A webhook answers at once, or with Answer the caller on, after the run, up to Wait at most. Each flow on it starts its own run; a request the workspace cannot start yet is kept and started when it can.
  • Security is on the webhook's page, under Security: Sender key, Signature check, Allowed addresses and Deliveries per minute (0 is no limit).

Common mistakes

  • Testing the URL in a browser. A browser sends GET, which gets 404. Send a POST, for example with curl.
  • Sending the key in another header. Only Authorization: Bearer, x-api-key and the key query parameter count; anything else gets 404.
  • Leaving out the content type. Your JSON then arrives as text in trigger.body.rawBody.
  • A new request id on each retry. Keep the same idempotency-key, so a request that did arrive starts no second run.
  • Signing the JSON after parsing it. Sign the exact bytes you send: a changed space or key order changes the signature.