Webhook trigger

A webhook trigger starts a run when an event reaches Loopfour over HTTP: from a provider your company has connected, or from any system that posts to your custom webhook URL. This page is about events coming in. To have Loopfour send run events to your own endpoint, see the Webhooks API.

Configuration

{
  "trigger": {
    "type": "webhook",
    "path": "vendor-portal",
    "provider": "stripe"
  }
}

The webhook trigger has no Studio block. Set it in the definition through the API.

Inbound routes

These routes sit at the API host root, outside /api/v1, and do not take an API key.

Any other provider name on POST /webhooks/:provider returns 404 with { "error": "Unknown provider: <name>" }. A failed signature returns 401 with { "error": "Invalid signature" }.

The routes are limited per sending IP address to 10,000 requests a minute.

Which workflows start

An event starts every active workflow in the receiving company whose trigger matches:

1. Custom route: the trigger's path equals the URL's :path segment. The comparison ignores case and treats ., - and _ as the same, so bill.received matches bill-received. Do not start path with a slash.
2. Provider routes: the trigger's provider equals the provider the event came from. Without provider, a trigger whose path equals the provider name also matches.

For HubSpot and Airwallex, the dedicated trigger types give event-level matching; see App event triggers.

Provider events are tied to a company through the connected account they name. A Stripe event with no account field, or for an account no company has connected, is answered { "received": true, "ignored": true } and starts nothing.

Run input

Each matched workflow gets a run with triggerType: "webhook" and this input:

{
  "webhookEvent": {
    "id": "a3f1c2d4-...",
    "provider": "custom",
    "eventType": "vendor-portal",
    "payload": {
      "billNumber": "B-2291",
      "vendor": "Northwind Supplies",
      "amount": 4180.5
    }
  }
}

Request headers are not passed to the run. Steps read the body with {{input.webhookEvent.payload.<path>}}.

Responses

The custom and Stripe routes answer:

{ "received": true, "eventId": "a3f1c2d4-...", "workflowsTriggered": 1 }

POST /webhooks/hubspot and POST /webhooks/airwallex answer { "received": true, "count": 1 }, where count is the number of events in the delivery that matched a connected account.

The route answers after the runs are queued; it does not wait for them to finish.

Filter events

The events field is not applied. Every event that reaches a matching route starts the workflow. To narrow it:

• Subscribe only to the events you need in the provider's own webhook settings.
• Put a Condition step first and branch on {{input.webhookEvent.eventType}} or a payload field.

Repeated events

Loopfour stores each event and its provider event id, but a redelivered event starts the workflow again. Make the workflow safe to repeat: look the record up before you create it, or use an action that updates a record by its number.

Test a webhook workflow

The custom route needs no signature:

curl -X POST https://workflow.loopfour.ai/webhooks/custom/$COMPANY_ID/vendor-portal \
  -H "Content-Type: application/json" \
  -d '{ "billNumber": "B-2291", "vendor": "Northwind Supplies", "amount": 4180.5 }'

For a provider workflow, call POST /api/v1/workflows/:id/run with an input.webhookEvent object shaped like the one above. See API trigger.