GitHubGet Hedhog updates in your inbox
New releases, fresh recipes, and breaking changes — no spam.
Core Submodule
webhook-integration
Manages inbound webhooks, event catalog and action/log pipelines.
Source path: libraries/core/src/webhook-integration
Module file: webhook-integration.module.ts
Introduction
The Webhook Integration submodule is HedHog's automation backbone, enabling event-driven workflows in both directions: receiving arbitrary payloads from external systems and dispatching actions or notifications when internal domain events occur.
Each inbound webhook integration is assigned a unique UUID that forms its receive URL: POST /webhook/:uuid. External systems — payment providers, form services, CI/CD pipelines, IoT devices — can POST any JSON payload to this URL. The server validates an optional HMAC signature (using the integration's secret against the raw request body) and passes the payload through the integration's ordered action pipeline.
An action pipeline is a sequence of actions that execute in order when the webhook fires. Five action types are available. Email sends a transactional message using a Mail submodule template, with payload fields substituted into template variables. HTTP Request performs an outbound call to any URL with configurable method, headers, body, timeout, and retry count. Internal API calls a HedHog endpoint by path, enabling webhook-triggered operations like creating records or generating reports. App Command dispatches a registered application command by slug with typed parameters, decoupling the webhook handler from specific implementation details. WhatsApp via Evolution API sends a message to a phone number or group through a configured Evolution integration profile.
Event-based outbound webhooks (event-webhook) subscribe to domain events from the integration event catalog and deliver the event payload to a configured external URL whenever the event fires. This is how HedHog pushes data out to external systems: when a user is created, a purchase completes, or a status changes, subscribed event webhooks are notified in near real time via the outbox processor.
Each webhook integration carries a UUID (used in the receive URL) and a secret (used for HMAC validation). Both can be independently regenerated via dedicated endpoints without recreating the integration or losing its action definitions, supporting credential rotation without downtime. POST /webhook-integration/:id/duplicate clones an integration including all of its actions, simplifying the creation of similar automation pipelines.
Every invocation is logged. GET /webhook-integration/:id/log returns paginated historical logs. GET /webhook-integration/:id/log/stream opens a Server-Sent Events stream for real-time debugging, making it possible to trace failures and verify payload transformations without switching to an external observability tool.
HTTP Endpoints
32 endpoints
List all webhook integrations.
- Query
- page, pageSize, search
List API tokens belonging to a user.
- Query
- userId (int)
Create a new API token for a user.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| userId | number | yes | — |
| name | string | yes | — |
List internal application routes available as webhook targets.
List application commands available for webhook action dispatch.
Get webhook integration details by ID.
- Params
- id (int)
Create a new webhook integration.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | yes | — |
| url | string | no | — |
| secret | string | no | — |
| headers | Record<string, string> | no | — |
Update a webhook integration.
- Params
- id (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | no | — |
| url | string | no | — |
| secret | string | no | — |
| headers | Record<string, string> | no | — |
Delete one or more webhook integrations.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| ids | number[] | yes | IDs to delete |
Regenerate the UUID used in the webhook receive URL.
- Params
- id (int)
Regenerate the secret token for a webhook integration.
- Params
- id (int)
Duplicate a webhook integration including its actions.
- Params
- id (int)
List actions defined for a webhook integration.
- Params
- id (int)
Create an action for a webhook integration.
- Params
- id (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| type | "email" | "whatsapp_evolution" | "http_request" | "internal_api" | "app_command" | yes | — |
| name | string | no | — |
| order | number | no | — |
| status | "active" | "inactive" | no | — |
| integration_profile_id | number | no | — |
| mail_id | number | no | Required when type is "email" |
| email_to | string | no | — |
| email_cc | string | no | — |
| email_bcc | string | no | — |
| http_url | string | no | Required when type is "http_request" |
| http_method | string | no | — |
| http_headers | Record<string, string> | no | — |
| http_body | string | no | — |
| http_timeout_ms | number | no | — |
| http_retry_count | number | no | — |
| internal_api_path | string | no | Required when type is "internal_api" |
| internal_api_method | string | no | — |
| internal_api_body | object | no | — |
| app_command_slug | string | no | Required when type is "app_command" |
| app_command_params | object | no | — |
| whatsapp_target_type | "phone" | "group" | no | — |
| whatsapp_target | string | no | — |
| whatsapp_template | string | no | — |
Update a webhook action.
- Params
- id (int), actionId (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| (same fields as POST action) | partial | no | All fields from create action are optional |
Delete actions from a webhook integration.
- Params
- id (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| ids | number[] | yes | IDs to delete |
List execution logs for a webhook integration.
- Params
- id (int)
- Query
- page, pageSize, sort?
Stream live execution logs for a webhook integration via SSE.
- Params
- id (int)
Receive an incoming webhook request and trigger configured actions.
- Params
- uuid (string)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| (payload) | any | no | Arbitrary JSON or form body forwarded to actions |
List all event-based webhook configurations.
- Query
- page, pageSize, search
Get an event webhook by ID.
- Params
- id (int)
Create a new event-based webhook.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| eventCatalogId | number | yes | — |
| url | string | yes | — |
| secret | string | no | — |
| headers | Record<string, string> | no | — |
Update an event-based webhook.
- Params
- id (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| eventCatalogId | number | no | — |
| url | string | no | — |
| secret | string | no | — |
| headers | Record<string, string> | no | — |
Delete one or more event webhooks.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| ids | number[] | yes | IDs to delete |
Duplicate an event webhook configuration.
- Params
- id (int)
List delivery logs for an event webhook.
- Params
- id (int)
- Query
- page, pageSize
List all events in the integration event catalog.
- Query
- page, pageSize, search
Return event catalog entries formatted as select options.
Get a catalog event by ID.
- Params
- id (int)
Create a new event catalog entry.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | yes | — |
| slug | string | yes | — |
| description | string | no | — |
| schema | object | no | JSON Schema of the event payload |
Update an event catalog entry.
- Params
- id (int)
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | no | — |
| slug | string | no | — |
| description | string | no | — |
| schema | object | no | — |
Delete one or more event catalog entries.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
| ids | number[] | yes | IDs to delete |
MCP Tools
Named tools callable by AI models via the Model Context Protocol (MCP).
core.webhooks.*Full CRUD and management operations for webhook integrations
core.event-webhooks.*Full CRUD operations for event-to-webhook bindings
core.integration-events.*Full CRUD and catalog operations for integration events