Webhooks API

Webhooks API

The Workflows API exposes two webhook surfaces:

• Inbound — endpoints under /webhooks/* that receive events from external providers (Stripe, HubSpot, Nango, your own systems) and route them to matching workflow triggers.
• Outbound — endpoints under /api/v1/webhook-endpoints that let you register URLs to receive notifications when workflow runs change state.

Inbound Webhooks

All inbound routes are mounted at the API root, not under /api/v1. Every inbound POST returns JSON and the same shared response shape:

{
  "received": true,
  "eventId": "evt_550e8400-e29b-41d4-a716-446655440000",
  "workflowsTriggered": 2
}

The full set of inbound routes mounted today is:

All inbound routes share a single rate-limit bucket of 10,000 requests / minute / IP.

Stripe

POST /webhooks/stripe

Receives events from Stripe directly. Supports both single-account workspaces and Stripe Connect — the connected account is read from event.account in the payload and resolved to a company via the connections table.

Headers

Behaviour

1. Reads the raw body and stripe-signature header.
2. If STRIPE_WEBHOOK_SECRET is set, verifies the signature using HMAC-SHA256 over ${timestamp}.${rawBody}. On mismatch the route returns 401 Invalid signature and persists the event with signatureVerified: "failed".
3. If the event has event.account, looks up the company that owns the matching Stripe-connected account via connections.externalAccountId. If no company is found the event is still recorded but no workflows are triggered.
4. Routes the event into matching workflow triggers and returns the standard response.

Example

stripe listen --forward-to localhost:3000/webhooks/stripe

curl -X POST "https://workflow.loopfour.ai/webhooks/stripe" \
  -H "Content-Type: application/json" \
  -H "stripe-signature: t=1705312000,v1=abc123..." \
  -d '{
    "id": "evt_test",
    "type": "invoice.paid",
    "account": "acct_xxx",
    "data": { "object": { "id": "in_test", "amount_paid": 9900 } }
  }'

Custom (per-tenant)

POST /webhooks/custom/:companyId/:path

Receives events from any external system into a specific company. The :path segment becomes the event type, and a workflow matches when its webhook trigger's path field equals that segment. The comparison is case-insensitive and treats ., -, and _ as equivalent, so order.received and order-received both match. Do not put a leading slash on path — it will never match.

The body is parsed as JSON when possible; non-JSON payloads are wrapped as { "rawBody": "..." }. No signature verification is performed — treat the URL itself as a shared secret and serve over HTTPS only.

curl -X POST "https://your-api.com/webhooks/custom/00000000-0000-0000-0000-000000000001/order-received" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "12345", "total": 99.99 }'

Provider Dispatcher

POST /webhooks/:provider

Generic dispatcher for providers that have a ProviderHandler registered in the @workflows/modules module package. Today the dispatcher accepts:

Each handler implements a four-method contract:

Events whose extractExternalAccountId returns null, or that do not match any active connections row for the provider, are dropped with an info-level log. Successful events are routed into matching workflow triggers and counted in the response:

{ "received": true, "count": 3 }

Unknown providers

A POST to /webhooks/:provider for a provider that has no registered handler returns:

{ "error": "Unknown provider: <name>" }

with HTTP 404.

Nango (internal)

POST /webhooks/nango

Receives OAuth lifecycle and provider events forwarded by Nango. This is how Salesforce, QuickBooks, NetSuite, PandaDoc, Slack, and Gmail events reach Workflows today.

This route is fail-closed: an unset NANGO_WEBHOOK_SECRET returns 500, and a request with no signature header or a signature that does not verify returns 401.

This route is configured in your Nango environment and should not be called directly.

Webhook Event Storage

Every inbound webhook is persisted to webhook_events before workflow matching, so events can be audited, replayed, and inspected even if no workflow consumed them.

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "companyId": "00000000-0000-0000-0000-000000000001",
  "provider": "stripe",
  "eventType": "invoice.paid",
  "eventId": "evt_external_123",
  "payload": { "...": "..." },
  "signatureVerified": "verified",
  "status": "processed",
  "workflowsTriggered": [
    { "workflowId": "wf_xxx", "runId": "run_xxx" }
  ],
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Error Responses

Workflow Trigger Configuration

To start a workflow from an inbound webhook, declare a webhook trigger in the workflow definition. path is required by the trigger schema; provider matches the inbound route (e.g. stripe, hubspot, justpaid, custom).

{
  "trigger": {
    "type": "webhook",
    "provider": "stripe",
    "path": "stripe"
  }
}

For custom webhooks, omit provider and set path to the :path segment of the URL:

{
  "trigger": {
    "type": "webhook",
    "path": "order-received"
  }
}

Matching is on provider (or, for custom, on path) only — every event that reaches the matched route starts the workflow. Narrow the events at the provider's own subscription settings, or with a Condition block at the top of the workflow.

See Webhook Triggers for the full trigger configuration reference.

Outbound Webhooks

Register outbound endpoints to receive notifications when workflow runs change state. These endpoints are managed via the standard x-api-key API.

Endpoint Management

Create Endpoint

POST /api/v1/webhook-endpoints

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "whe_550e8400-e29b-41d4-a716-446655440000",
    "name": "Invoice System",
    "url": "https://api.example.com/webhooks/workflows",
    "secret": "whsec_abc123...",
    "events": ["workflow.completed", "workflow.failed"],
    "workflowIds": ["550e8400-e29b-41d4-a716-446655440000"],
    "headers": { "Authorization": "Bearer your-token" },
    "status": "active",
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

Event Types

Delivery Payload

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "workflow.completed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
  "workflowName": "Invoice Processing",
  "runId": "run_660e8400-e29b-41d4-a716-446655440001",
  "companyId": "00000000-0000-0000-0000-000000000001",
  "status": "completed",
  "triggerType": "webhook",
  "startedAt": "2024-01-15T10:29:55.000Z",
  "completedAt": "2024-01-15T10:30:00.000Z",
  "durationMs": 5000,
  "input": { "invoiceId": "inv_123" },
  "output": { "processed": true }
}

Failed runs include an error object:

{
  "error": {
    "code": "STEP_ERROR",
    "message": "API rate limit exceeded",
    "stepId": "sync-to-crm"
  }
}

Signature Verification

Every outbound delivery is signed with HMAC-SHA256 in a Stripe-compatible format.

import crypto from 'node:crypto';

function verifyWebhook(rawBody, signatureHeader, secret) {
  const [tPart, vPart] = signatureHeader.split(',');
  const timestamp = tPart.split('=')[1];
  const received = vPart.split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Always verify against the raw request body — re-serializing will produce a different hash.

Retry Policy

Failed deliveries (any non-2xx response or transport error) are retried with exponential backoff:

After 8 failed attempts the delivery is marked permanently failed. After 10 consecutive failures across deliveries, the endpoint is automatically disabled and must be re-enabled by setting status: "active" on the endpoint.

Test, List Deliveries, Retry

POST /api/v1/webhook-endpoints/:id/test

{ "eventType": "workflow.completed" }

Sends a synthetic delivery and returns the upstream HTTP status and response body so you can validate signing and connectivity end-to-end.

GET /api/v1/webhook-endpoints/:id/deliveries?status=failed

Returns the recent delivery attempts for an endpoint with cursor-based pagination.

POST /api/v1/webhook-endpoints/:id/deliveries/:deliveryId/retry

Re-queues a single delivery without waiting for the backoff schedule.

Best Practices

• Be idempotent. Providers may retry. Use eventId to deduplicate and write workflow actions so a repeated event has the same outcome.
• Respond fast. Acknowledge inbound webhooks immediately — workflow execution is asynchronous, so your handler does not need to wait for the run to finish.
• Always verify when a secret is available. Configure STRIPE_WEBHOOK_SECRET and NANGO_WEBHOOK_SECRET in production. NANGO_WEBHOOK_SECRET is mandatory wherever Nango webhooks are received — that route is fail-closed and returns 500 without it. The Stripe route instead skips verification when its secret is unset, which is convenient in development but should never be relied on in an environment that accepts real provider traffic.
• Monitor signatureVerified and status. A spike in failed or ignored is a strong signal that a provider rotated a secret or that a connection is misconfigured.