Deliver to a webhook

POST/api/webhooks/{token}

A published workflow’s public address: any request to it starts a production run, and the answer can be the run’s result.

Needs no API token: the token in the address is the key. See Call a workflow’s webhook.

Parameters

Path

tokenRequired · string: The workflow’s webhookToken, from Publish a workflow.

Query

asyncOptional · string: true answers 202 as soon as the run is queued. Anything else waits, up to 30 seconds.

Headers

Idempotency-KeyOptional · string: Up to 255 characters. A retry with the same key and the same method, query and body starts no second run: it gets the first run’s answer, with Idempotency-Replayed: true. Kept 24 hours.

Body

Any body, any Content-Type, up to 5 MiB. It becomes {{trigger.body}}.

A Return Response step

A Return Response step decides the answer instead: its status, headers and body. The run headers come with it.

Responses

200OK
The run finished within 30 seconds. The body is the last step’s output, or {}. X-Run-Id and X-Run-Status are set.
202Accepted
Still going after 30 seconds, paused, or waiting for a free slot; or ?async=true. The body has runId.
400VALIDATION_ERROR
A NUL in the address, or a body that couldn’t be read.
401UNAUTHORIZED
The trigger’s Authentication, or an app’s signature check, failed. Nothing runs.
404NOT_FOUND
“Webhook not found.” The address is wrong or was replaced, the workflow isn’t published, or its trigger isn’t one this address is for.
405METHOD_NOT_ALLOWED
The trigger’s methods leaves this method out. Allow lists the ones it takes.
409CONFLICT
The run was cancelled, while it waited for a slot or while it ran. Or the Idempotency-Key’s first delivery is still being recorded (Retry-After: 1), or its run has since been deleted.
413PAYLOAD_TOO_LARGE
The body is over 5 MiB. Nothing runs.
422VALIDATION_ERROR
This Idempotency-Key was already used with a different request.
429RATE_LIMITED
This address sent more than WEBHOOK_RATE_LIMIT requests this minute. Retry-After says when to try again.
429CONCURRENCY_LIMIT
The workflow is at its runs-at-once limit and is set to Refuse.
429RUNS_WAITING_LIMIT
Too many runs are already waiting, for the organization or this workflow.
500
The run failed. Read the run for the reason.
503SERVICE_UNAVAILABLE
The address couldn’t be looked up just now, or nothing can run the workflow. Retry after Retry-After.
503ACCOUNT_SUSPENDED
The account is suspended. Retry-After: 3600.
503PAUSED
A self-hosted installation has no license. Retry-After: 3600.
503WORKER_UNAVAILABLE
Nothing can run the workflow just now, and nothing was recorded. Retry-After: 10. With ?async=true, the run is queued instead.
503PIECES_UNAVAILABLE
GoRunner couldn’t check which apps this workspace may use. Nothing changed. Try again.
503STORAGE_UNAVAILABLE
The run finished, but its answer couldn’t be read back. Read it with the ID in X-Run-Id.
504
The run failed on a time limit.

Any call can also answer: 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 415 INVALID_CONTENT_TYPE · 503 BUSY. See Errors.

Request

GORUNNER="https://api.gorunner.io"
WEBHOOK_TOKEN="your-webhook-token"

curl -i -X POST "$GORUNNER/api/webhooks/$WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orderId": "A-1001"}'

const GORUNNER = "https://api.gorunner.io";
const WEBHOOK_TOKEN = process.env.WEBHOOK_TOKEN;

const res = await fetch(
  `${GORUNNER}/api/webhooks/${WEBHOOK_TOKEN}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ orderId: "A-1001" }),
  },
);
const answer = await res.json();
console.log(res.status, res.headers.get("X-Run-Id"), answer);

import os, requests

GORUNNER = "https://api.gorunner.io"
WEBHOOK_TOKEN = os.environ["WEBHOOK_TOKEN"]

res = requests.post(
    f"{GORUNNER}/api/webhooks/{WEBHOOK_TOKEN}",
    json={"orderId": "A-1001"},
)
print(res.status_code, res.headers.get("X-Run-Id"), res.json())

Response · 200 OK, the last step’s output, with no data envelope

json

{
  "orderId": "A-1001",
  "accepted": true
}

Every field

The delivery, any content type: it becomes the run’s trigger data ({{trigger.body}}).

200 OK: a body.

Response · 202 Accepted

dataobject

runIdUUID

statusstring

running, paused, waiting or pending (pending when not waited for: queued). Absent with ?async=true.

messagestring

A sentence for a person: what to do next.

waitstring

overloaded: not waited for, because the server held as many waiting callers as it may.

One of overloaded.

pollstring

With wait: overloaded: where to read the run.