Inbound webhooks
Accept provider webhooks while the app is parked; verified, queued and retried.
On this page
Gregale can accept a webhook while your app is scaled to zero. It verifies the
provider request, writes it to the durable invocation queue, and returns 202 Accepted. The scheduler then wakes the app and POSTs the provider JSON payload
to the configured path. Failed deliveries use the existing async retry and
dead-letter lifecycle. An explicitly bound workflow callback is completed
directly instead of creating an app invocation.
Stripe is the first supported provider. Inbound webhooks are available on the Hobby, Pro, and Scale plans.
Create an endpoint
POST /v1/apps/my-api/inbound-webhooks
Authorization: Bearer fp_live_...
Content-Type: application/json
{
"name": "stripe-primary",
"provider": "stripe",
"signing_secret": "whsec_...",
"delivery_path": "/internal/stripe"
}
The response contains endpoint_url. Copy that URL into Stripe when creating
the webhook destination. The URL is shown only in the create response; Gregale
stores only a hash of its token. The Stripe signing secret is sealed and never
returned.
{
"id": "...",
"name": "stripe-primary",
"provider": "stripe",
"delivery_path": "/internal/stripe",
"enabled": true,
"signing_secret_masked": "***",
"endpoint_url": "https://api.gregale.dev/v1/hooks/gwh_..."
}
Delivery
After Stripe's signature verifies and the event is durable, Stripe receives:
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"receipt_id": "...",
"status": "accepted",
"duplicate": false,
"accepted_at": "2026-09-22T15:30:00Z"
}
Your app receives a POST at delivery_path with the Stripe JSON payload.
Gregale adds these headers:
X-Faas-Invocation-Source: inbound_webhookX-Gregale-Webhook-Provider: stripeX-Gregale-Webhook-Event-Id: evt_...X-Gregale-Webhook-Endpoint-Id: ...
The original Stripe-Signature is deliberately not forwarded because it may
have expired during a cold start or retry. X-Faas-Invocation-Source is
platform-owned and overwritten after queued headers are applied; use it to
distinguish a verified webhook delivery from ordinary public or async traffic.
Treat the X-Gregale-* fields as metadata only after checking that source.
Gregale drops X-Gregale-Webhook-* and X-Gregale-Event-* headers from public
requests, so a caller cannot send them to your app directly or through an
async route.
Stripe retries of the same event for the same endpoint return the same receipt
ID with duplicate: true and do not enqueue a second delivery.
Stripe sees 202 as soon as the event is accepted, so Gregale owns the retries
from then on. A handler that throws, or answers 408 or 429, is retried under the
app's retry_policy; when the attempts run out, or the handler refuses the
event with another 4xx, the delivery lands in the
dead letters, where you replay it after a fix
(gregale dlq replay). Resending the event from Stripe does not deliver it
again: it is the same receipt.
Backlog
Accepted deliveries wait in the app's queue under the plan's queue caps, the
same caps a queue send meets: pending messages per app and backlog bytes per
account (see queue limits). While either is
full, a verified delivery gets 429 inbound_webhook_backlog_full with
Retry-After: 60 and nothing is accepted, so the provider retries the same
event later.
Rate limit
An account's endpoints accept a bounded number of verified deliveries a
minute: Free 60, Hobby 1,200, Pro 3,000, Scale 6,000. Past it a delivery gets
429 inbound_webhook_rate_limited with Retry-After. Deliveries that fail
signature verification are limited separately, per client IP.
Start a stored workflow
An endpoint can start a published stored workflow directly through its
workflow-binding resource. This opts into stored workflow delivery for that
endpoint. Signature verification, sealed secrets and endpoint ownership retain
their existing behavior. The durable receipt and captured workflow definition
commit before acknowledgement; no relay handler is needed. See
stored workflow authoring for
binding, filters, provider retry behavior and receipt inspection.
Complete a workflow callback
An account-authorized client can bind a wait_for_callback step to one
known Stripe object event:
PUT /v1/workflows/runs/RUN_ID/callbacks/CALLBACK_ID/webhook-binding
Authorization: Bearer fp_live_...
Content-Type: application/json
{"endpoint_id":"ENDPOINT_ID","event_type":"payment_intent.succeeded","object_id":"pi_123"}
Use an existing endpoint owned by the same app. Gregale still verifies the
Stripe signature and extracts the event type and data.object.id. An exact
match writes the signed JSON as the callback result in the durable workflow
ledger and acknowledges with {"callback_id":"...","status":"received","duplicate":false}.
It does not enqueue an app invocation. A signed event that does not match a
binding follows the ordinary delivery path above. A matched event that arrives
after the callback closed is acknowledged with status: "ignored" to stop
provider retries. Bind before the event arrives.
The binding can be inspected with GET or revoked with DELETE at the same
path. The endpoint URL and Stripe secret remain managed through the existing
endpoint API; they are never returned by the binding API. Revocation affects
later deliveries; an already verified request may still finish its callback.
Failed-delivery alerts can use failure_source: inbound_webhook; the any
source aggregate includes webhook deliveries as well.
Manage endpoints
GET /v1/apps/{slug}/inbound-webhooks
GET /v1/apps/{slug}/inbound-webhooks/{id}
PATCH /v1/apps/{slug}/inbound-webhooks/{id}
DELETE /v1/apps/{slug}/inbound-webhooks/{id}
PATCH can enable or disable ingress, change delivery_path, or rotate the
provider signing_secret. Changing the secret does not change the endpoint
URL. For 24 hours after a rotation, deliveries signed with the old secret
still verify, so you can update the provider after rotating. Deleting or disabling an endpoint affects only future ingress; already
accepted deliveries remain in the invocation queue.
Spotted a problem on this page? Tell us