Request callbacks
Give a request a callbackUrl and Formstep sends one signed POST to it when the request ends: completed, expired or canceled. Your workflow picks up from that POST.
Set callbackUrl on requests.create. It must use HTTPS, resolve to a public
address, be at most 2,048 characters and carry no user name or password. Any port works, and so does a public IP address. A URL that
breaks a rule fails with VALIDATION_ERROR and the reason CALLBACK_URL_NOT_ALLOWED. The URL cannot be changed
after the request is created.
localhost does not work; while you test, use a tunnel as in
Receive and verify the callback.
What fires, and when
| Event | When |
|---|---|
| request.completed | The recipient submitted. Carries the answers. |
| request.expired | The expiry passed while the request was still pending. |
| request.canceled | You or your automation withdrew it. |
All three go to the same URL, so check type before you read answers. An expiry reaches you within 5 minutes of
expiresAt.
What arrives
{
"id": "evt_n57fq2wd8kx3mz9cv4hb6tp1ry0js5ga",
"type": "request.completed",
"createdAt": "2026-03-04T09:31:40.000Z",
"apiVersion": "2026-09-24",
"test": false,
"data": {
"request": {
"id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
"externalId": "run-42",
"status": "completed",
"outcome": "approve",
"language": "en",
"recipient": { "email": "ada@acme.com", "name": "Ada" },
"metadata": { "runId": "run-42" },
"context": { "case_id": "CASE-9" },
"createdAt": "2026-03-04T09:20:00.000Z",
"completedAt": "2026-03-04T09:31:40.000Z"
},
"form": { "id": "jx75hdx8vb5hy1x85gm17nqgkn8f674g", "name": "Vendor onboarding", "snapshotId": "kh7cm2v9bq4xw8d1ntz6p3fy5rg0sa7e" },
"submission": {
"id": "jd73pw5qz8xmc2kv9nb4h6tr1fy0ge8s",
"respondentEmail": "ada@acme.com",
"submittedAt": "2026-03-04T09:31:40.000Z",
"updatedAt": null,
"editCount": 0,
"pdfUrl": null,
"language": "en"
},
"answers": { "company_name": "Acme", "contacts": [{ "name": "Ada" }] },
"display": { "company_name": "Acme", "contacts": "Ada" },
"aiValidations": {
"company_check": { "status": "passed", "fields": ["company_name"] }
}
}
}An expired or canceled request sends only data.request, with the time it ended:
{
"id": "evt_n59kc4tx2mw8vq7zd3hf6bp0ry1gs5ja",
"type": "request.expired",
"createdAt": "2026-03-11T09:20:00.000Z",
"apiVersion": "2026-09-24",
"test": false,
"data": {
"request": {
"id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
"externalId": "run-42",
"status": "expired",
"language": "en",
"recipient": { "email": "ada@acme.com", "name": "Ada" },
"metadata": { "runId": "run-42" },
"context": { "case_id": "CASE-9" },
"createdAt": "2026-03-04T09:20:00.000Z",
"expiredAt": "2026-03-11T09:20:00.000Z"
}
}
}{
"id": "evt_n53wd8pz6kq2xv9mc4ht7bf1ry0gs5je",
"type": "request.canceled",
"createdAt": "2026-03-05T14:02:10.000Z",
"apiVersion": "2026-09-24",
"test": false,
"data": {
"request": {
"id": "m17ayhcnj9xvzkff3atek49bdd8f6872",
"externalId": "run-42",
"status": "canceled",
"language": "en",
"recipient": { "email": "ada@acme.com", "name": "Ada" },
"metadata": { "runId": "run-42" },
"context": { "case_id": "CASE-9" },
"createdAt": "2026-03-04T09:20:00.000Z",
"canceledAt": "2026-03-05T14:02:10.000Z",
"cancelReason": "Vendor signed up by phone"
}
}
}data.requestis always there, with yourexternalId,metadataandcontextunchanged.externalIdandmetadataarenullwhen you set none. It carries the timestamp of whichever ending happened:completedAt,expiredAt, orcanceledAtwith an optionalcancelReason.outcomeis present only when the recipient answered a decision question:approve,declineorchanges. Expired and canceled requests have none.form,submission,answersanddisplayappear on completion only, in the shape a submission webhook carries, never withdata.schema. Expired and canceled requests carry none of them.form.snapshotIdis the published version the recipient answered.submission.respondentEmailis the request's recipient email, ornullwhen the request names none, andupdatedAtis alwaysnullandeditCount0, since a completed request cannot be edited.submission.pdfUrlis a URL only when the form keeps a submission PDF.answersis keyed by field key, with repeating groups nested as one object per item. A choice answer is the option key; its label is indisplayunder the same key. Each field type's shape is in Answer shapes.aiValidationsis there when the form has AI Validations. Its fields are described on the webhooks reference.testistruefor a test request. Branch on it, or drop the event.
requests.sample returns this envelope for any form without a real request, which helps when you map fields before the first one ends.
Deduplicate on id
id stays the same across every retry and every replay of the same event. If acting twice would hurt, such as a second
invoice or a second ticket, store the ids you have handled and skip a repeat.
Headers
Content-Type: application/jsonandUser-Agent: FormstepX-Formstep-Event-IdandX-Formstep-Event-Type, the same values asidandtypein the body, so you can deduplicate and route before parsingX-Formstep-Signature: t={unix seconds},sha256={hex}, on every callback
Verify the signature
A callback is signed exactly like a webhook: the same header, an HMAC-SHA256 of the timestamp, a dot and the raw body. Use the verifier on Webhooks reference: Signing. Two things differ:
The key is the workspace's request signing secret, one secret for every callback in the workspace. A webhook uses its own secret.
- Every callback is signed. A webhook is signed only when it has a secret.
To find the secret, open API Keys in the workspace sidebar and look for the Request signing secret card. Only the workspace owner sees it: click Reveal secret, then copy it. The owner can read it again at any time. The secret is never returned over the API or MCP, which is why an agent with nobody to set up a receiver should poll instead.
Regenerating has no grace period
When the owner regenerates the secret, the old one stops working at once, even for callbacks being retried. Update your receiver first, then regenerate.
When a valid callback fails the check, the cause is almost always the body. Parsing the JSON and serializing it again changes the bytes, so hash the body exactly as it arrived. The other common cause is a regenerated secret the receiver has not picked up yet.
A resume URL is not authentication
A workflow tool's hard-to-guess resume URL can leak into logs, and it does not prove who sent the body. Verify the signature anyway.
Retries
Answer with a 2xx within 10 seconds. A callback gets eight attempts over about four hours, and every attempt sends the same body with the
same id, as it was when the request ended.
| Your response | What Formstep does |
|---|---|
| 2xx | Done. The callback is marked delivered. |
| 408, 429, 5xx | Retries, and honours a Retry-After longer than the next step, up to 24 hours. |
| Timeout or connection error | Retries on the same schedule. |
| Any other 4xx | Stops. Your endpoint refused the body, and sending it again cannot help. |
| Blocked URL | Stops at once. A host that does not resolve, a private address or a non-HTTPS URL cannot become allowed. Redirects are never followed, so a 3xx stops too. |
A callback gets a longer budget than a webhook, because a workflow run is waiting on it:
| Webhook | Request callback | |
|---|---|---|
| Attempts | 5, over about two hours | 8, over about four hours |
| A 408 from your endpoint | Stops | Retried |
| When attempts run out | The integration pauses after 5 failed attempts in a row, which one event can use up. See Retries | The request gets a Callback failed badge, and the workspace owner gets one email per request; nothing pauses |
When a callback never lands
The request page shows the callback URL and what happened to it. Once the callback has failed for good, because its attempts ran out, your
endpoint answered with a 4xx other than 408 or 429, or its URL was blocked, requests.get carries
callbackFailedAt in epoch milliseconds. A delivery or a replay clears it. The answers are not lost: requests.get
still returns them.
Check the URL. A workflow tool's resume URL belongs to one run, and a run that was deleted or re-created no longer answers on it. The URL cannot be changed and a replay goes to the same one, so when it is gone for good, read the answers with
requests.getinstead.Check what your endpoint returned. A 4xx other than 408 or 429 stops the retries at once, so a receiver that rejects a valid body never gets a second try.
Fix the receiver, then send the callback again: Replay on the request in the Requests page, or requests.replayCallback. A replay gets a fresh 8 attempts and sends the same body with the same
id, so a receiver that deduplicates is safe. Replay within 30 days: after that the delivery record is gone, and the replay fails with409 CONFLICTand reasonNO_CALLBACK_TO_REPLAY.
Subscriptions hear the same events
A callback URL belongs to one request. To send every request of a form to one receiver, subscribe once instead: the Zapier, Make and n8n
apps do this for you, and from code you call webhooks.create with
request_completed, request_expired or request_canceled. A subscription gets the same body under its
own event id, with the webhook retry budget. It is signed only when you passed a
signingSecret to webhooks.create, and it carries no User-Agent: Formstep header. A request with
both a callback URL and a subscription sends to both. Test requests reach no subscription, and Replay resends only the
callback.