Inbound traffic: webhooks into contract triggers
Outside systems send traffic to an extension: a payment provider’s webhook, a button click, a reply to a message. The sender expects an answer within a
few seconds and often retries when it does not get one. Stage therefore owns the endpoint, keeps what arrived, answers the sender at once and then
delivers the request to the extension. The extension verifies the request and raises the
triggers its contract declares, such as
Payments.PaymentSucceeded. Today a raised trigger resumes the workflow runs that wait for it about the same correlation key. Starting reactions and
workflows from a trigger needs trigger routes (IContractTriggerRoutes), which no language support registers yet, so a trigger that resumes nothing is
answered NOT_ROUTED; see raise a trigger.
This page is the reference for what Stage does with the traffic. The protocol messages are in the protocol reference, the services an extension calls to raise a trigger are in the host services reference, and the model side is the systems and abilities page of Screenplay.
The path of a request
Section titled “The path of a request”sender ──POST /extensions/Payments/webhook──▶ Stage ──▶ stored ──▶ 202 Accepted ──▶ sender │ └─ dispatcher ──▶ activate the extension (if it is not running) ──▶ HandleHttp (raw body and headers, every attempt) │ verify the signature with the secret setting │ RaiseTrigger("PaymentSucceeded", key, correlation) ▼ workflow runs that wait for the trigger (reactions need trigger routes)- Receive. A request to
/extensions/<System>/<path>with a method that may change something (POST,PUT,PATCH,DELETE) is stored with its method, path, query, raw body and headers, then acknowledged with202 Accepted. The sender never waits for the extension, so a cold start, a slow handler or a restart does not cost the sender a timeout. - Deliver. A dispatcher inside Stage delivers stored requests. An extension that is not running is activated first. Every attempt carries the raw body exactly as it arrived, so a signature computed over the body verifies.
- Verify and raise. The extension verifies the request with its secret settings and raises contract triggers through the
host services, or answers a pending
answers laterinvocation. It answers200or202when it has taken the request.
A request that only reads (GET, HEAD, OPTIONS) is not stored. It is passed to the extension and answered with what the extension answers, because such
a request asks a question, such as a verification challenge, and the sender needs the answer.
Stage answers the sender itself in these cases, and stores nothing:
| Answer | When |
|---|---|
404 |
The system has no backend, or the extension is running and declares no route for the path. |
413 |
The body is larger than 1 MiB. |
503 with Retry-After: 60 |
More than MaxOpen requests wait for delivery, so an anonymous sender cannot fill storage. |
A path that the extension does not declare is only discovered when the extension is running. Until then Stage stores the request and the extension is asked, so
the request ends as rejected in the Workbench instead of being answered with 404.
What the extension answers
Section titled “What the extension answers”The extension’s answer to HandleHttp decides what becomes of the stored request:
| The extension answers | The request becomes | Retried |
|---|---|---|
2xx |
Delivered | No. |
4xx other than 408, 425 and 429 |
Rejected: it did not verify, or is not one the extension handles. | No. The same request would be refused again. |
408, 425, 429, 5xx, no answer, or the extension cannot be reached |
Retrying | Yes, with a growing wait. |
| Every attempt failed | Failed | Only when an operator retries it. |
An extension that finds the signature invalid answers 401. That makes Stage reject the request for good and keep it visible, rather than retry it.
Delivery is at least once. If Stage stops between the extension taking a request and Stage recording it, the request is delivered again after the restart.
Every attempt carries the same delivery identity, as invocation_id and idempotency_key in the request context and as DeliveryId on the C# SDK’s call, so the
extension deduplicates on it. The TypeScript, Kotlin and Go SDKs do not pass the delivery identity to an HTTP handler. Stage requires a deduplication key on every trigger. Once trigger routes exist, raising the same trigger with the same key again will find the runs the
first raise started. Today Stage does not deduplicate a resume: a wait the first raise resolved cannot be resolved again, but a repeated raise resumes any
wait about the same correlation that is open by then, so the extension deduplicates on the delivery identity before it raises.
Security
Section titled “Security”The endpoint is anonymous by design: the sender of a webhook is not a Stage user. Four things make that safe.
The extension verifies the request. Stage cannot know how a provider signs. The extension reads the signing secret from its secret settings,
verifies the signature over the raw body, and answers 401 when it does not verify. Nothing in the model holds a credential. The C# SDK’s
WebhookSignature does this with an HMAC-SHA256 and a
comparison that takes the same time however many characters match. An extension raises a trigger only after the request verified.
Replays are absorbed. A request that is identical to one Stage already holds, in method, path, query and body, is acknowledged and not delivered again:
while the first is still waiting, and for ReplayWindow (24 hours) after it arrived. This also absorbs the sender’s own retries. The signature headers are not
part of the comparison, because a sender’s retry carries a fresh timestamp and signature. A request that was given up on as failed is not a replay: a sender
that retries after every attempt failed is asking for the delivery to be made. A captured request replayed after the window is delivered, so the extension must
also refuse a stale one: sign and check a timestamp with WebhookSignature.Verify(..., timestamp, ..., now, tolerance).
The trusted actor is the extension, not the sender. Once trigger routes exist, the reactions a trigger starts will run as the actor extension:<System>,
recorded on the run, with the trigger’s causation naming the delivery. Only an extension that presented the credential from its handshake can raise a trigger, and only one its own contract
declares. The anonymous sender never becomes the identity a reaction runs as.
Secrets stay out of storage and out of the Workbench. Cookie, Authorization, Host and connection headers are never stored or forwarded. The Workbench
lists a request’s status, size and header names, never its body or header values.
Resume a workflow that waits
Section titled “Resume a workflow that waits”A raised trigger starts no reactions yet: that needs trigger routes, which no language support registers. What it does today is resume workflow runs that wait for it, and for that the extension names what the trigger is about:
await host.Trigger("PaymentSucceeded", payloadJson, deduplicationKey: evt.Id, correlationKey: evt.PaymentId);Here host is a C# HostServices, such as an ability’s call.Host: an HTTP handler has none yet. Only the C# SDK accepts a correlation key; the
TypeScript, Kotlin and Go SDKs raise a trigger without one, so from them a trigger resumes no waiting run.
Runs that wait for Payments.PaymentSucceeded about the same correlation resume, with the payload as the data of the wait. Without a correlation key nothing
resumes, so until trigger routes exist the raise is answered NOT_ROUTED: a trigger that starts nothing and resumes nothing is reported, never silently accepted. A trigger raised before the wait it
is meant for is open resumes nothing and is not remembered: the workflow reads the state it needs when it reaches the wait.
Watch and retry in the Workbench
Section titled “Watch and retry in the Workbench”Stage keeps the newest 5000 requests. The Workbench lists the newest 200 of them, with each request’s status, attempts, when the next attempt is due, and what the last attempt ended with. The tooling endpoints behind it exist in the sandbox and are not mapped by a published runtime:
| Request | Meaning |
|---|---|
GET /stage/extensions/deliveries?status=failed |
At most the newest 200 requests, newest first, as { "deliveries": [...], "failed": n }, where failed counts the failed requests in that list. status is optional and is pending, retrying, delivered, rejected or failed; another name answers 400. |
POST /stage/extensions/deliveries/retry with { "id": "..." } |
Puts a failed or rejected request back for another round of attempts and answers 202. An unknown request answers 404; one that is neither failed nor rejected answers 409. |
Each listed request carries its id, system, method, path, query, status, attempts, nextAttempt, responseStatus, reason, received,
completed, replays, bodyBytes and headers (the header names only).
Settings
Section titled “Settings”Under Stage:Extensions:Inbound:
| Setting | Default | Meaning |
|---|---|---|
MaxAttempts |
8 |
Attempts before a request is shown as failed. |
RetryDelay |
00:00:05 |
The wait before the second attempt. Each following wait doubles. |
MaxRetryDelay |
00:15:00 |
The longest wait between two attempts. |
ReplayWindow |
24:00:00 |
How long an identical request counts as a replay. |
MaxOpen |
1000 |
Requests that may wait at once. Past it Stage answers 503. |
PollInterval |
00:00:02 |
How long the dispatcher sleeps when nothing is due. |
AttemptTimeout |
00:00:30 |
How long one attempt may take. |
Limits
Section titled “Limits”- A route is declared by the backend, and Stage learns it at the handshake. A path the extension does not declare is rejected at delivery, not answered with
404by Stage, until the extension has run once. - A
POSTis always acknowledged with202and an empty body. A provider that requires a synchronous answer to aPOST, such as a challenge handshake, is not served yet. - No SDK gives an HTTP handler the host services yet, so an SDK-built handler cannot read a secret setting through Stage, raise a trigger or answer an invocation.
- Only the C# SDK has
WebhookSignature, the correlation key and the delivery identity on the call; the other SDKs compare the signature themselves.