# Webhook

<!-- meta: type=webhook; location=Custom Events; category=Trigger; platforms=Joomla and WordPress (where applicable) -->

## Overview

Starts your flow when another system sends data to your unique webhook address — for example a form submission, payment alert, or custom integration.

When this trigger fires, JOrchestrator starts the flow and passes the incoming event or request data to the next connected step. Configure filtering, payload shape, and security on the **Design** tab.

## Why use this node

Webhook is a **trigger** in the **Custom Events** group. Triggers start a flow. They listen for an external signal — a CMS event, inbound HTTP call, payment notification, or schedule — and pass the incoming data to the first downstream step.

Typical reasons teams add **Webhook** to a flow:

- Accept form or lead submissions from a landing page hosted outside Joomla/WordPress
- Receive inventory, shipping, or fulfilment callbacks from warehouse or ERP systems
- Let a mobile app or custom script start a flow with a JSON payload
- Bridge Zapier, Make, or internal tools into JOrchestrator without writing a plugin

## When it runs

This **trigger** starts the flow when its signal fires on your linked site or when an inbound request matches its configuration. Downstream steps receive the trigger payload as their input.

## Example workflows

Common patterns on the canvas:

1. **Webhook** → **Set JSON** (normalize fields) → **Send Email** (notify team)
2. **Webhook** → **If** (VIP flag) → **Slack Message** / **Send Email**
3. **Webhook** → **Iterator** (line items) → **Insert Row** (log each line)

## How to set it up

On the Design tab, describe the fields you expect to receive so later steps can use them. Link the flow to a domain and keep it Active so the address stays registered.

## Good to know

The webhook address is shown on the Design tab once the flow is saved and active.

## Properties panel

The designer shows these tabs for this node:

| Tab | Purpose |
|-----|---------|
| **Info** | Plain-language description and output payload fields for downstream steps |
| **AI** | Optional assistant for trigger setup (paid plans) |
| **Design** | Trigger configuration, payload schema, and inbound settings |

### System (automatic — not edited by the user)

These fields are managed by the designer or runtime — you do not type into them directly:

| Property key | Label | Type | Required | Visible when | Notes |
|--------------|-------|------|----------|--------------|-------|
| `_nodeId` | Node ID | `node-id` | No | — | — |
| `_inboundWebhookUrl` | Inbound webhook URL | `webhook-inbound-url` | No | — | Steps to go live:
1. Link a domain and save this flow (your site needs a flow id in the URL).
2. Copy the URL into your external app or script.
3. Replace the token placeholder with your API Key or Bearer Token from Joomla Node Configuration → Events → Webhook Configuration, or set those fields on this node.
4. Send requests using the HTTP method configured below (default POST). |
| `inputSchema` | Input JSON Schema (optional) | `json-schema` | No | — | Define the JSON body shape callers should send. Fields appear as {{webhook.fieldName}} downstream and inbound payloads are validated against this schema when non-empty. |

### User-configured — General tab

| Property key | Label | Type | Required | Visible when | Notes |
|--------------|-------|------|----------|--------------|-------|
| `label` | Label | `text` | No | — | Node label |

### User-configured — Design tab

| Property key | Label | Type | Required | Visible when | Notes |
|--------------|-------|------|----------|--------------|-------|
| `method` | HTTP Method | `select` (`GET` \| `POST` \| `PUT` \| `DELETE`; default: `POST`) | No | — | HTTP verb callers must use (GET, POST, PUT, or DELETE). A mismatch returns 403. Choose the same method your sending system uses — most integrations use POST. |
| `apiKey` | API Key (optional) | `secret-text` | No | — | From Joomla Node Configuration → Events → Webhook Configuration, or override here Optional override of Joomla Node Configuration → Events → Webhook Configuration. When set (here or globally), every request must authenticate with this key via Authorization: Bearer …, X-Api-Key, or ?token= on the URL. Leave blank to use global config only or allow unauthenticated calls when no global key is set. |
| `bearerToken` | Bearer Token (optional) | `secret-text` | No | — | From Joomla Node Configuration → Events → Webhook Configuration, or override here Optional override of the global bearer token. Works like API Key — callers send Authorization: Bearer …, X-Api-Key, or ?token=. If either API Key or Bearer Token is configured, requests without a valid token are rejected. |
| `webhookSecret` | Webhook Secret (for HMAC) (optional) | `secret-text` | No | — | Secret for signature verification Shared secret for HMAC-SHA256 signature verification when Verify Signature is enabled. Your sender signs the raw request body (optionally prefixed with the timestamp) and sends the digest in the signature header. |
| `verifySignature` | Verify Signature (optional) | `toggle` (default: `false`) | No | — | When on, requests must include a valid HMAC signature using Webhook Secret. When off, your site checks HTTP method and optional API Key / Bearer Token only. |
| `signatureHeader` | Signature Header Name (optional) | `text` (default: `X-Webhook-Signature`) | No | — | X-Webhook-Signature HTTP header carrying the HMAC signature (default X-Webhook-Signature). Common formats: hex digest, base64, or sha256=…. Must match what your sender uses. |
| `timestampHeader` | Timestamp Header Name (optional) | `text` (default: `X-Webhook-Timestamp`) | No | — | X-Webhook-Timestamp Optional header with a Unix timestamp in seconds (default name X-Webhook-Timestamp). When present with Verify Signature on, old requests are rejected using Timestamp Tolerance (replay protection). |
| `timestampTolerance` | Timestamp Tolerance (seconds) (optional) | `number` (default: `300`) | No | — | 300 Maximum age in seconds for the timestamp header (default 300). Requests outside this window are rejected. Ignored when the timestamp header is missing or tolerance is 0. |
| `ipWhitelist` | IP Whitelist (comma-separated) (optional) | `textarea` | No | — | 192.168.1.1, 10.0.0.0/8 Comma-separated IP addresses or CIDR ranges allowed to call this webhook (e.g. 192.168.1.1, 10.0.0.0/8). Leave empty to allow any client IP. Others receive 403. |
| `requireHttps` | Require HTTPS Only (optional) | `toggle` (default: `false`) | No | — | When enabled, plain HTTP requests are rejected with 403. Turn on for production webhooks exposed on the public internet. |
| `rateLimit` | Rate Limit (requests/minute) (optional) | `number` | No | — | 100 Optional cap on inbound requests per minute for this trigger. Leave blank for no limit. |
| `headers` | Headers (optional) | `textarea` | No | — | {"Content-Type": "application/json"} Reference notes for expected request headers (JSON object). Not enforced on inbound calls — use for your own integration documentation. |

### CMS site configuration (not on this node's properties panel)

Credentials, API keys, mailers, SMTP, and integration defaults are configured in the CMS plugin under **Node Configuration**, not per step on this node. Link the flow to a domain before testing CMS-backed fields.

## Output payload fields

After this step runs, later nodes can reference these fields using placeholders such as
`{{webhook.body}}`.

| Field key | Type | Description |
|-----------|------|-------------|
| `body` | object | Raw content — response text, file bytes (often base64), or message body. |
| `headers` | object | HTTP response headers as an object. |
| `query` | object | URL query parameters from the inbound request. |
| `params` | object | Request parameters object. |

## Related nodes

Other steps in the same area of the palette:

- **Jorchestrator Cron** (`event-jorchestrator`) — Custom Events
- **PayPal Payments Pro** (`event-paypal`) — Custom Events
- **Stripe** (`event-stripe`) — Custom Events
- **Zapier Webhook** (`event-zapier`) — Custom Events