Aller au contenu principal

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​

NameTypeRequiredDescription
resultjsonNoWebhook request data: payload, raw_body, headers, method, path, query_params, event_type, content_type, idempotency_key, received_at, status, reason
successbooleanNoWhether the webhook passed validation and filters

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Listen PortportnumberNo9090TCP port to listen on for incoming webhooks
Listen Pathlisten_pathstringNo/URL path to accept requests on

Auth​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Auth Modeauth_modeenumNononenone, header_secret, hmac_sha256How to validate incoming requests
Webhook Secretwebhook_secretsecretNoShared secret for header or HMAC validation
Secret Headersecret_headerstringNoX-Webhook-SecretHeader containing the secret (for header_secret mode)
Signature Headersignature_headerstringNoX-Hub-Signature-256Header containing HMAC signature (for hmac_sha256 mode)

Filter​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Filter Pathfilter_pathstringNoOnly accept requests matching this path (empty = all)
Filter Methodfilter_methodstringNoOnly accept this HTTP method (empty = all)
Filter Eventsfilter_eventsstringNoComma-separated list of allowed event types (empty = all)

Errors​

CodeDescription
PORT_BIND_FAILEDCould not bind to the configured listen port
LISTENER_CANCELLEDContext was cancelled before a request arrived
HMAC_VERIFICATION_FAILEDHMAC-SHA256 signature does not match
SECRET_MISMATCHWebhook 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.

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.