Webhook Triggers

A webhook trigger runs your workflow when an external system POSTs to a unique URL. Use it for services not in the integration catalog or for ad-hoc HTTP integrations.

#Setting up

Add a webhook trigger to a workflow’s entry node. Configure:

• Method: POST (default), GET, PUT, PATCH, or DELETE
• Authentication: None, API Key, or HMAC
• Payload schema (optional): declare expected fields so the variable picker offers typed suggestions

Saving generates a unique URL:

https://rills.ai/api/webhooks/{shortId}

Share that URL with the system that will call it.

#Authentication

#None

Any caller can trigger the workflow. Fine for local testing or trusted callers behind another auth layer. Don’t use this for public-facing endpoints.

#API key

The caller passes a key in a header (default: X-API-Key). Generated on creation and only shown once so store it somewhere safe.

POST https://rills.ai/api/webhooks/abc123
X-API-Key: your-key-here

#HMAC signature

The caller signs the request body and includes the signature in a header.

Format: sha256=<hex_digest>, GitHub-compatible, so GitHub webhooks work out of the box.

The HMAC secret is generated on creation and encrypted at rest.

#Payload

The request body is parsed as JSON and made available as trigger data. Downstream nodes access it via {{trigger.field}}.

// Incoming POST body
{ "event": "order.created", "order_id": "abc-123" }

// Reference downstream
{{trigger.event}}      // "order.created"
{{trigger.order_id}}   // "abc-123"

In custom code: ctx.trigger.event.

#Status codes

Responses returned by the webhook endpoint:

#Monitoring

Each webhook tracks last triggered time, total triggers, consecutive failures, and last error. View these in the workflow’s trigger configuration.

#See also

• Workflows : node taxonomy and run lifecycle
• First workflow tutorial : step-by-step build
• Integrations : connecting services already in the catalog