# Webhooks
Start Plandalf automations from generated catch URLs or send outbound HTTP requests from automation actions.
Source: /docs/api/webhooks
Last modified: 2026-06-20
## API reference
- Method: `POST`
- Path: `/hooks/catch/{sequence}/{trigger}`
- Request URL: `https://your-plandalf-app-host/hooks/catch/{sequence}/{trigger}`
- Authentication: `Secret catch URL`
- Playground: `simple`
- Operation ID: `triggerAutomationWebhook`
Plandalf automation supports webhooks in two directions. A generated catch URL can start a sequence from an external system, and a Send Webhook action can call your own endpoint during a sequence.


> **Inbound catch URLs**
>

    External systems send an HTTP request to a generated Plandalf URL. Plandalf records the payload and starts the matching automation trigger.


> **Outbound webhook actions**
>

    Plandalf sends an HTTP request to a URL you configure in an automation action.


> **Catch URLs are public endpoints**
>

  Inbound automation webhooks are routed under `/hooks/catch/SEQUENCE_ID/TRIGGER_ID` and do not require dashboard authentication. Treat each generated URL as a secret, rotate it by replacing the trigger if it leaks, and validate important payload fields before using them for fulfillment.


## Inbound automation webhooks

Use an inbound webhook when something outside Plandalf should start a sequence: a form submission, an email platform event, a backend account event, or a promo enrolment flow.


### Create or open a sequence


    In Automations, create the sequence that should run after the external event.


### Add the Plandalf Webhook trigger


    Choose the Plandalf app and the Webhook trigger. The trigger stores `trigger_type: "webhook"` and exposes a generated catch URL.


### Copy the catch URL


    The trigger editor shows the Webhook URL and a copy button. Promo enrolment automations also expose the same catch URL from the promo email/enrolment panel.


### POST a real payload


    Send a test request with the fields your sequence actions need. The test panel waits for a webhook event and then lets you select the received payload as a sample record.


### Path parameters


- `sequence` (string; required):
    Sequence route key embedded in the generated catch URL.


- `trigger` (string; required):
    Trigger route key embedded in the generated catch URL.


### Request body


- `email` (string):
    Buyer or participant email when the automation should personalize downstream actions.


- `ref` (string):
    Optional reference value from the source system, campaign, or form.


- `source` (string):
    Optional origin label that helps branch, filter, or audit the automation run.


### Send a sample payload


```bash title="POST generated catch URL"
curl -X POST "https://your-plandalf-app-host/hooks/catch/SEQUENCE_ID/TRIGGER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "ref": "launch-list-42",
    "source": "newsletter-form",
    "offer": "spring-launch"
  }'
```


### Accepted webhook response


```json title="200 workflow started"
{
  "success": true,
  "message": "Workflow started",
  "workflow_id": 1842
}
```


### Skipped trigger response


```json title="200 trigger skipped"
{
  "success": true,
  "message": "Webhook received but trigger was skipped",
  "workflow_id": null
}
```


## Payload and metadata

The inbound webhook controller passes the request body into the automation trigger payload and records request metadata for the automation event.


- `webhook_payload.email` (string):
  Promo enrolment templates use `{{webhook_payload.email}}` as the default participant email and reference value.


- `headers` (object):
  Plandalf keeps relevant headers such as content type, user agent, forwarded IP headers, API key/signature headers, and signature headers. `authorization` and `x-api-key` values are masked in recorded metadata.


- `method` (string):
  The route accepts any HTTP method, but use `POST` with JSON for predictable automation payloads.


## Test an inbound webhook

When no webhook event has been received yet, the trigger test endpoint returns a waiting state with the catch URL. Send a real request to that URL, refresh the test panel, and choose the received event as the sample record for downstream field mapping.


### Waiting for the first webhook event


```json title="200 waiting state"
{
  "success": false,
  "message": "No webhook received yet. POST a real payload to the catch URL below to generate test data.",
  "samples": [],
  "data": {
    "trigger_id": 91,
    "trigger_name": "Webhook",
    "waiting_for_webhook": true,
    "catch_url": "https://your-plandalf-app-host/hooks/catch/SEQUENCE_ID/TRIGGER_ID"
  }
}
```


## Outbound webhook actions

Use the Send Webhook action when Plandalf should call your backend, CRM, fulfilment system, or automation router during a sequence.


- `url` (string; required):
  The endpoint to call. Plandalf validates that the value is a valid URL before sending.


- `method` (GET | POST | PUT | DELETE | PATCH; required, default: POST):
  The HTTP method for the outgoing request.


- `payload` (JSON string):
  Optional JSON payload. Leave it empty for `GET` requests.


- `headers` (map):
  Optional key-value headers for the outgoing request. If a payload is present and no `Content-Type` is supplied, Plandalf sends `Content-Type: application/json`.


### Outbound action result


```json title="200 outbound action"
{
  "success": true,
  "status_code": 200,
  "response_body": "{\"ok\":true}",
  "headers": {
    "content-type": ["application/json"]
  },
  "url": "https://api.example.com/plandalf",
  "payload": "{\"email\":\"buyer@example.com\"}",
  "method": "post"
}
```


## Related docs


  - [Live events](/docs/sdk/events): Use browser-side events when you need client behavior around checkout and offers.
  - [API authentication](/docs/api/authentication): Authenticate protected API routes before mixing API calls with automation workflows.
  - [Going live](/docs/going-live): Check webhook workflows with a real test event before relying on live fulfillment.