Webhook Gateways
Webhook Gateways give your tenant HTTPS endpoints that external systems can call. A request posted to a gateway is received by Studio, stored with its payload, and can start an Action Flow automatically — for example processing invoice events pushed by your ERP, or reacting to notifications from a CRM.
![The Webhook Gateways page listing endpoints with their URLs, security methods, and statuses(assets/gateways/webhooks-overview.png)
When To Use Webhooks
- Start an Action Flow the moment something happens in another system, without polling.
- Receive structured JSON events (orders, invoices, tickets, contacts) as Action Flow input.
- Integrate SaaS products that offer outgoing webhooks with your Studio automations.
Create A Webhook
- Open Gateways > Webhooks from the main navigation.
- Choose New Webhook.
- Give the webhook a name and, optionally, a description.
- Pick an authentication method (see below) and, optionally, restrict callers by IP.
- Save. The endpoint URL is ready immediately — use Copy to register it with the sender.
If you chose an authentication method, the generated secret is shown once after saving. Store it right away; it cannot be viewed again, only rotated.
Tenant admins manage webhooks; all tenant users can read the received requests.
Authentication
Each webhook has one authentication method, checked on every request:
| Method | How the caller authenticates |
|---|---|
| None | No authentication — anyone who knows the URL can call the gateway. The URL contains two random identifiers, but prefer a real method for anything sensitive. |
| HMAC signature | The caller signs the raw request body with HMAC-SHA256 using the shared signing key and sends the signature in a header (default X-Dooap-Signature, value sha256=<hex>). Optionally, a timestamp header can be required so old requests are rejected (replay protection). |
| Secret header | The caller sends the shared secret in a header (default X-Dooap-Webhook-Secret). |
| Basic auth | The caller uses HTTP Basic authentication with the configured username and the generated secret as password. |
| URL secret | The caller appends the shared secret as a query parameter (default ?secret=…). Note that URLs may end up in the sender's logs. |
An IP allowlist (comma-separated addresses or CIDR ranges) can be combined with any method, including None. Requests from other addresses are rejected.
![Editing a webhook: authentication method, signature header and encoding, replay protection, and IP allowlist(assets/gateways/webhooks-security.png)
Use Rotate secret to generate a new secret. The old secret stops being accepted within about five minutes, so update the caller promptly.
Calling A Webhook
External systems POST JSON to the endpoint URL:
POST {endpoint URL}
Content-Type: application/json
{ "type": "invoice", "status": "received", "invoiceId": "INV-1001" }
Requests must be JSON and at most 128 KB. Studio replies 202 Accepted with a request id
(also findable in the Trigger Stream); the matched Action Flows run asynchronously. A
Slack-style url_verification challenge is answered automatically so handshake-based
senders can verify the endpoint.
Trigger An Action Flow From A Webhook
- In the Action Flow's settings, select the Webhook Received trigger.
- Optionally select specific webhooks — with none selected, the Action Flow triggers on requests to any of the tenant's webhooks.
- Optionally add filter rules that inspect the JSON payload (for example
$.type Equals invoice), so only matching requests start the Action Flow. - Publish the Action Flow.
Inside the run, the payload is available as inputs.triggerPayload, along with
inputs.webhookId (the gateway id) and inputs.triggerReceived (the receive timestamp).
The legacy names inputs.webhookPayload and inputs.webhookReceived keep working as
aliases of the two above.
Monitor Received Requests
Received requests appear as events in the Trigger Stream page, together with all other trigger activity of the tenant. Each event records the payload, when the request arrived, which webhook it arrived at, the caller's IP address, and the Action Flow runs it started — including per-run status and links to the run logs. A request that matched no published Action Flow completes with a "no actions" status, so misconfigured integrations are easy to spot.
Requests are deliberately not kept as a separate list: webhook volume can be very high, and the Trigger Stream's event store is built for that scale.
Things To Know
- Deleting a webhook stops it from receiving requests immediately; its URL is never reused by another tenant.
- Disabled webhooks reject requests with
404. - Webhooks that were configured on OpenAPI Apps before this feature existed were migrated automatically, and their endpoint URLs kept working unchanged. They start with authentication set to None — consider adding an authentication method.