Webhook

The Webhook node turns your workflow into an HTTP endpoint accessible from any external system. It enables two main flows: starting new executions and resuming existing executions — all through a simple HTTP call. Think of this node as the front door of your workflow: external systems knock (send an HTTP request), and your flow decides what to do with what they bring.

Only one Webhook node per canvas is allowed.

Webhook URL

The URL is generated by the node itself. Open it in Studio and use Copy URL: the trailing identifier is the Webhook node ID, not a separate identifier. Calls come in through the Jelou gateway. The node generates two URLs, depending on which version of the workflow you want to run. Production — runs the latest published version of the workflow:

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{channel}/{nodeId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY"

Test (draft) — runs the workflow as it stands on the canvas right now, including changes you haven’t published:

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{channel}/test/{nodeId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY"

{channel} is the workflow channel in lowercase: whatsapp, web, instagram, facebook, slack, teams, twitter, or custom.

The gateway requires authentication. Send your API key in the x-api-key header on every webhook call; without that header the response is 401 Unauthorized. Create and manage it in API Keys.

Already have an integration pointing at the previous host, workflows.jelou.ai? It keeps working and you do not need to migrate it urgently. The gateway URL applies to new integrations.

Always copy the URL from the node instead of building it by hand.

The examples on this page use the production URL. To test against the draft, replace {nodeId} with test/{nodeId}.

Operation modes

The Webhook node operates in two modes, automatically determined by the presence of the executionId:

Start new execution

When the request does not include an executionId, the webhook creates a new workflow execution from scratch. Use case: An external system (CRM, ERP, payment gateway) needs to trigger an automated process in Jelou. Starting a new execution requires the user identifier. The example passes it as ?userId=; the other way is covered in Webhook in Workflows.

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{channel}/{nodeId}?userId=%2B593999999999" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -d '{"event": "new_order", "customer": "12345"}'

Resume existing execution

When the request includes an executionId, the webhook resumes an execution that was paused waiting for an external response. Use case: A payment gateway notifies that the payment was processed, and the flow should continue where it left off.

curl -X POST https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{channel}/{nodeId} \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -d '{"executionId": "abc-123", "status": "paid"}'

The executionId can be sent in the body (using the dot notation path configured in the node) or as a query param executionId. This allows using HTTP methods like GET that don’t have a body.

Configuration

Variable name

Define the name under which webhook data will be stored within the $webhook variable. Data received by the request will be available at $webhook.<variableName>. For example, if you define myWebhook, you can access the body via {{$webhook.myWebhook.body}}, headers via {{$webhook.myWebhook.headers}}, etc.

HTTP Method

Select which HTTP methods the webhook accepts. Supports GET, POST, PUT, PATCH, and DELETE.

The HTTP method is required. If you publish the node without selecting one, every request to the URL is rejected. Select it before publishing.

For methods without a body (like GET), the executionId for resuming must be sent as a query param: ?executionId=abc-123.

Resume multiple times (oneTimeOnly)

By default, an execution can be resumed more than once by the webhook. If you need to restrict this — for example, in payment integrations where a confirmation should only be processed once — you can enable the “Resume only once” option in advanced settings.

Setting	Behavior
oneTimeOnly disabled (default)	The webhook can resume the same execution multiple times
oneTimeOnly enabled	The webhook only resumes the execution once; subsequent attempts are ignored

`$webhook` variable

When a request reaches the Webhook node, all request information becomes available through the $webhook variable. It works similarly to $memory and $context.

Property	Description	Example
`$webhook.<variableName>.body`	HTTP request body	`{"event": "payment_success", "amount": 50}`
`$webhook.<variableName>.headers`	Request headers	`{"content-type": "application/json"}`
`$webhook.<variableName>.query`	URL query params	`{"ref": "campaign-123"}`
`$webhook.<variableName>.method`	HTTP method used	`POST`
`$webhook.<variableName>.mode`	Execution mode	`new` or `resume`
`$webhook.<variableName>.executionId`	Current execution ID	`exec-abc-123`
`$webhook.<variableName>.isNewExecution`	Whether it’s a new execution	`true` or `false`

Usage example in the flow

Assuming you defined myWebhook as the variable name, you can use the properties in any subsequent node:

# In a Conditional node
{{$webhook.myWebhook.body.event}} == "payment_success"

# In a Text node
The payment of {{$webhook.myWebhook.body.amount}} was processed successfully.

# In an API node
Authorization: {{$webhook.myWebhook.headers.authorization}}

Webhook in Workflows

The Webhook node is available in Workflows, allowing conversational flows to be triggered or resumed by external events.

Considerations for Workflows

New executions in Workflows

To start a new Workflow execution via webhook, the request must include the user identifier (e.g., phone number for WhatsApp). This is needed so the Workflow can send messages to the user through the corresponding channel.You can send it in two ways:

In the body: configure the User ID field in the node panel with the path (dot notation) where the identifier arrives.
As a query param: append ?userId= to the URL, with nothing to configure in the panel.

# ID in the body, with the "User ID" field configured as `phone`
curl -X POST https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/whatsapp/{nodeId} \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -d '{"phone": "+593999999999", "event": "reminder"}'

# ID as a query param
curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/whatsapp/{nodeId}?userId=%2B593999999999" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY" \
  -d '{"event": "reminder"}'

If the identifier does not arrive through either route, the webhook responds with an error stating that userId is missing.

Resuming executions in Workflows

To resume an existing execution, only the executionId is needed. The system already has the user context from the original execution.

Platform restrictions

On platforms like WhatsApp, if there is no active session (24-hour window) between the user and the channel, the webhook won’t be able to send messages directly. In these cases, you can use an HSM node within the flow to send an approved template that reopens the conversational window.

Versioning

The webhook always executes the latest published version of the Workflow. If there is more than one channel of the same type connected to the project, the most recent one is used.

Inheritance in child workflows

When a child Workflow inherits webhooks from its parent Workflow, if the child Workflow receives a request, it overwrites the parent flow’s webhook data. The $webhook data propagates to child executions (internal Workflow nodes).

Testing (Draft)

To test the webhook during development (before publishing), the node generates a test URL that includes a /test segment before the node ID:

curl -X POST "https://gateway.jelou.ai/workflows/v2/webhooks/skill/{workflowId}/{channel}/test/{nodeId}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $JELOU_API_KEY"

The /test URL executes the current draft of the workflow, so you can iterate without affecting the published version. It also does not require the user identifier: those parameters come from the Workflow Tester.

In Workflows, draft testing is done through the Workflow Tester. User parameters configured in the Workflow Tester also apply when invoking the webhook in test mode.

Backward compatibility

Webhooks created before this update continue to work without changes. The improvements only apply going forward:

Existing webhooks keep their legacy configuration, including the “variable” field that stored data in $context.
New webhooks always store information in the new $webhook entity, offering a richer and more consistent structure.
Previous URLs are still served, as noted in Webhook URL.

For legacy webhooks that had a context variable configured, the variable configuration component will still be shown for backward compatibility. In new webhooks, this field does not appear since data is always stored in $webhook.

Common use cases

Payment notifications

Receive confirmations from gateways like Stripe or MercadoPago and resume the purchase flow.

CRM integrations

Trigger automated flows when a record is created or updated in your CRM.

E-commerce events

Process events like cart abandonment, order shipment, or returns.

IoT automations

Receive data from sensors or devices to trigger alert or processing flows.

Getting Started

Developer

Jelou CLI

Outbound Messaging

Management

Marketplace

Channels

Configuration

Billing

Webhook URL

Operation modes

Start new execution

Resume existing execution

Configuration

Variable name

HTTP Method

Resume multiple times (oneTimeOnly)

`$webhook` variable

Usage example in the flow

Webhook in Workflows

Considerations for Workflows

Testing (Draft)

Backward compatibility

Common use cases

Payment notifications

CRM integrations

E-commerce events

IoT automations

​Webhook URL

​Operation modes

​Start new execution

​Resume existing execution

​Configuration

​Variable name

​HTTP Method

​Resume multiple times (oneTimeOnly)

​$webhook variable

​Usage example in the flow

​Webhook in Workflows

​Considerations for Workflows

​Testing (Draft)

​Backward compatibility

​Common use cases

Payment notifications

CRM integrations

E-commerce events

IoT automations

Webhook URL

Operation modes

Start new execution

Resume existing execution

Configuration

Variable name

HTTP Method

Resume multiple times (oneTimeOnly)

`$webhook` variable

Usage example in the flow

Webhook in Workflows

Considerations for Workflows

Testing (Draft)

Backward compatibility

Common use cases