API Webhook
Category: Trigger
Node id: api-webhook
Starts an HTTP listener on a configurable port, waits for an inbound webhook request, validates it (secret or HMAC-SHA256), applies filters, and outputs the parsed request data
What it does
- Starts HTTP listener on configurable port
- HMAC-SHA256 signature verification (GitHub/Stripe style)
- Header secret validation
- Content-type aware parsing (JSON + form-encoded)
- Event type extraction from headers and payload
- Configurable event type, path, and method filtering
- Query parameter extraction
- Idempotency key tracking
Use cases
- Receive GitHub/GitLab webhook events for CI/CD pipelines
- Accept Stripe payment event notifications
- Ingest ADT messages from hospital webhook endpoints
- Trigger FHIR Subscription notifications
- Receive IoT device event payloads
Runtime
- Performance tier:
io-bound - Execution mode:
trigger - Default timeout: 300 seconds
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Webhook request data: payload, raw_body, headers, method, path, query_params, event_type, content_type, idempotency_key, received_at, status, reason |
success | boolean | No | Whether the webhook passed validation and filters |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Listen Port | port | number | No | 9090 | TCP port to listen on for incoming webhooks | |
| Listen Path | listen_path | string | No | / | URL path to accept requests on |
Auth
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Auth Mode | auth_mode | enum | No | none | none, header_secret, hmac_sha256 | How to validate incoming requests |
| Webhook Secret | webhook_secret | secret | No | Shared secret for header or HMAC validation | ||
| Secret Header | secret_header | string | No | X-Webhook-Secret | Header containing the secret (for header_secret mode) | |
| Signature Header | signature_header | string | No | X-Hub-Signature-256 | Header containing HMAC signature (for hmac_sha256 mode) |
Filter
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Filter Path | filter_path | string | No | Only accept requests matching this path (empty = all) | ||
| Filter Method | filter_method | string | No | Only accept this HTTP method (empty = all) | ||
| Filter Events | filter_events | string | No | Comma-separated list of allowed event types (empty = all) |
Errors
| Code | Description |
|---|---|
PORT_BIND_FAILED | Could not bind to the configured listen port |
LISTENER_CANCELLED | Context was cancelled before a request arrived |
HMAC_VERIFICATION_FAILED | HMAC-SHA256 signature does not match |
SECRET_MISMATCH | Webhook secret header does not match |
Runtime notes
- result.status is 'accepted', 'rejected', or 'filtered' — use this to branch on validation outcome without checking success alone
- The node blocks until a request arrives or the context times out (default 300s) — always set an appropriate execution timeout
- Only the first inbound request is processed; subsequent requests receive HTTP 503 and are discarded
- payload is null when the body cannot be parsed as JSON or form-encoded — check raw_body for the original content
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Something unclear? Send documentation feedback by email.