Arm a one-shot capture of the next real webhook delivery
Requires scope
workflow:runArms this workflow to CAPTURE the next delivery to its public webhook URL, for 120 seconds. This is how you get a real provider's payload into the editor without publishing.
What a caller must know:
- There is no separate test URL.
testUrlis the workflow's own webhook path (/api/webhooks/{webhookToken}) — the same address a producer is already registered against. It is returned as a PATH, not an absolute URL; prefix it with the API's public base. - It is one-shot: the first delivery disarms the listener, so a retry or a refresh cannot double-fire. It also expires by itself after
expiresInSeconds. - What happens on that delivery depends on publication state. If the workflow is NOT active, the delivery runs the DRAFT and is recorded as
environment: "test",triggerType: "webhook"— honestly both. If the workflow IS active, the delivery is an ordinary production run; arming does not divert it. - Watch the outcome on
GET /api/workflows/{id}/listen-stream, which pushes atest_event_capturedevent carryingrunIdand the capturedtriggerData. - Arming requires Redis; without it this is 503.
- No request body is read. Re-arming simply restarts the 120-second window.
Authorization
bearerAuth AuthorizationBearer <token>
An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.
In: header
Path Parameters
id*string
Workflow id (UUID).
Format
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/workflows/497f6eca-6276-4993-bfeb-53cbbbba6f08/listen"{ "data": { "testUrl": "string", "expiresInSeconds": 0 }}