> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Receive external HTTP requests to start or resume workflow executions

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.

> [!NOTE]
>
> Only **one Webhook node per canvas** is allowed.

> [!WARNING]
>
> The webhook request limit is **400 requests per minute**.

***

## 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:

```bash theme={null}
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:

```bash theme={null}
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`.

> [!WARNING]
>
> 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](https://docs.jelou.ai/en/guides/settings/api-keys.md).

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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](#webhook-in-workflows).

```bash theme={null}
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.

```bash theme={null}
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"}'
```

> [!TIP]
>
> 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.

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

> [!NOTE]
>
> 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

> [accordion] 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.
>
> ```bash theme={null}
> # 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"}'
> ```
>
> > [!NOTE]
> >
> > If the identifier does not arrive through either route, the webhook responds with an error stating that `userId` is missing.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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:

```bash theme={null}
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.

> [!WARNING]
>
> 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](#webhook-url).

> [!NOTE]
>
> 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

> [card] Payment notifications
>
> Receive confirmations from gateways like Stripe or MercadoPago and resume the purchase flow.

> [card] CRM integrations
>
> Trigger automated flows when a record is created or updated in your CRM.

> [card] E-commerce events
>
> Process events like cart abandonment, order shipment, or returns.

> [card] IoT automations
>
> Receive data from sensors or devices to trigger alert or processing flows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.