1
Add the node
On the Graph, Add a node → Webhook. Connect it to the next step.
2
Publish and Start
Publish, then Start on Overview. Copy Endpoint URL. Rotate secret shows Signing secret once — copy it too. The secret is not shown again.
Input
Inspector Settings. Empty-field rules for the Graph: Previous nodes. URL and signing secret are on Overview, not on this node.Output
Menu and empty fields: Previous nodes. Tokens below: one Trigger on the Graph (Trigger). JSON keys from the POST body are not extra rows — use Body, or parse it in Code.
Call
SendPOST to the Endpoint URL with a JSON body. That JSON is what the Run sees.
The Instance must be Watching. If you pressed Stop, POST returns 503. Start on Overview, then retry.
202 means the POST was accepted and a Run was queued — not that the Agent already finished.
id is this delivery (use it to check status). runId is the Run. thread is the conversation id you sent, or null.
In the snippets, paste Endpoint URL into url (the whole https://…/api/hooks/… string). Paste Signing secret into secret.
Who is calling
The Signing secret proves the POST is yours. Pick one:- Bearer — send the secret in
Authorization. Fastest way to get a 202. - HMAC — do not put the secret in
Authorization. Sign the body instead. See HMAC.
Same request twice
Every POST must include headerIdempotency-Key. You invent the value — typically the id of the event in your system, such as order-123. Up to 256 characters.
If the HTTP client retries, send the same key and the same JSON. Riggery returns the same 202 and does not start a second Run.
The same key with different JSON returns 409. Use a new key for a new event.
HMAC
Use HMAC when you do not want the secret inAuthorization. It also proves the JSON was not changed on the way.
Sign these bytes, in order: the current unix time (seconds), a single dot, then the exact body you send (an extra space or newline breaks the check). HMAC-SHA256, hex digest. Header:
X-Riggery-Signature: t=TIME,v1=HEX
TIME must be within 5 minutes of the server clock.
--data-binary keeps the body identical to what you signed.
One-shot or conversation
With nothread, each POST is separate. The Agent does not see earlier webhook POSTs. The 202 field thread is null.
To keep a conversation (later POSTs share history), pick an id such as crm-42 and send it every time: header X-Webhook-Thread or JSON field thread. Letters, numbers, ., _, -; 1–128 characters. Do not use event. If you set both header and JSON, they must be the same string.
Files
To attach files, POSTmultipart/form-data: field payload is the JSON as a string; files use form names files or file. For HMAC, sign the full multipart body, not only the JSON.
Check the Run
202 is not the Agent’s answer. It only means Riggery accepted this POST and started a Run. If your server must know whether the Workflow finished and what it returned, look up that POST by theid in the 202 JSON.
The lookup URL is the Endpoint URL with /deliveries/ and the id appended. Example: you POST to https://riggery.dev/api/hooks/xxxxxxxx and the 202 body has "id": "cldelivery01". You then GET:
https://riggery.dev/api/hooks/xxxxxxxx/deliveries/cldelivery01
Same Bearer or HMAC as the POST. For HMAC, sign an empty body (this GET has no JSON).
Call this URL again until run.status is succeeded or failed. If a Graph HTTP request is waiting for a person to confirm, status stays waiting_approval.
run.output.text is the result when the Run succeeded. run.error is set when it failed. While the Run is still going, status is queued or running and those fields are empty.