Skip to content

Buffer webhooks into a queue or a workflow ​

A hook checks the sender's signature and answers 200 at once. With an action, it can also hand each accepted request to the job engine:

ActionDoes
enqueueSends one message to a queue on the distribution
workflow_startStarts a workflow run of a function
workflow_signalSends a signal to the run whose id is in the payload, such as a payment provider confirming a charge

The sender never waits for your code: the action runs right after the 200, and runs once per accepted request, so a sender that retries does not create a second message or run.

You need hook.write, plus queue.send for enqueue or workflow.write for the workflow actions. The queue or function must already exist on the distribution. The web app does not manage hooks yet. Use an agent, the CLI, or the API.

1. Send each request to a queue ​

This example buffers Stripe events into the queue stripe-events, so a function can process them in batches at its own pace.

text
Add a Stripe webhook receiver called stripe to acme-marketing that puts every event on the
stripe-events queue. The signing secret is whsec_8Qp…
bash
echo '{"action": {"kind": "enqueue", "queue": "stripe-events"}}' |
  edge hooks create acme-marketing --slug stripe --preset stripe --secret 'whsec_8Qp…' --config -
bash
curl -s -X POST \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "stripe", "preset": "stripe", "secret": "whsec_8Qp…",
        "config": { "action": { "kind": "enqueue", "queue": "stripe-events" } } }'

The agent runs edge_hook_create. Each message's body is the verified request:

json
{
  "hook": "stripe",
  "receipt_id": "rcpt_01M4Y…",
  "idempotency_key": "evt_3Q…",
  "headers": { "stripe-signature": "…" },
  "payload": { "id": "evt_3Q…", "type": "payment_intent.succeeded", "data": { … } }
}

payload is the parsed JSON (or form fields, or the text) of the request. headers holds the provider headers Edge forwards, such as x-github-event. A body over 128 KiB cannot be queued, and the receipt fails with too_large.

Each receipt queues one message, even when Edge retries the action. The consumer still sees at-least-once delivery, as with any queue, so dedupe on receipt_id.

2. Or start a workflow run ​

Use workflow_start when each request begins a longer process, for example a sign-up form that starts an onboarding run:

json
{"action": {"kind": "workflow_start", "script_id": "01JBQZ8XKT4A9WN2CDEFGH5RM7", "name": "onboard"}}

The run's input is the same object as a queued message. Set it with the commands in section 1, or with edge hooks update for a hook that already exists.

3. Or resume a waiting run ​

A workflow step that answers wait for a signal can be resumed by the provider itself. Put the run id somewhere the provider sends back, such as Stripe's metadata, and tell the hook where to find it:

text
Make the stripe hook on acme-marketing send the paid signal to the workflow run whose id is
at $.data.object.metadata.run_id.
bash
echo '{"action": {"kind": "workflow_signal", "run_id_from": "$.data.object.metadata.run_id", "signal": "paid"}}' |
  edge hooks update acme-marketing stripe --config -
bash
curl -s -X PATCH \
  https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe \
  -H "Authorization: Bearer $EDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "config": { "action": { "kind": "workflow_signal",
        "run_id_from": "$.data.object.metadata.run_id", "signal": "paid" } } }'

run_id_from is a path into the payload: $ followed by .key and [index] steps. The signal's payload is the same object as a queued message, so the next step reads the event at signal.payload.payload. The run must be on the same distribution; otherwise the receipt fails with not_found. A run that has already finished fails it with run_finished.

4. Check the result ​

Each receipt records what its action did:

text
Show the last receipts for the stripe hook on acme-marketing.
bash
edge hooks receipts acme-marketing stripe
bash
curl -s https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/hooks/stripe/receipts \
  -H "Authorization: Bearer $EDGE_TOKEN"
resultMeans
{"message_id": "msg_…", "duplicate": false}Queued
{"run_id": "wfr_…", "created": true}Run started
{"run_id": "wfr_…", "delivered": true}Signal delivered; false means Edge keeps it until the run waits for it
{"error": "queue_full", "retrying": true}The queue is full, the send rate is over its limit, or the distribution has too many active runs; Edge tries again every 5 minutes for 24 hours
{"error": "not_found", …}, too_large, run_finishedThe receipt failed; the action does not run again

Next ​