Webhook Configuration

Trigger workflows from external systems with HTTP webhooks, authentication, idempotency, and event filtering

External systems send HTTP requests to a unique URL to trigger your workflows.

Setting up a webhook trigger

Add a webhook trigger to the entry node in the workflow builder. Configure a path (must start with /) and an HTTP method. Supported methods: GET, POST (default), PUT, PATCH, DELETE.

When the workflow is saved, Rills generates a unique endpoint URL:

https://{your-domain}/api/webhooks/{shortId}

The shortId is a 12-character identifier created automatically. Share this URL with the external system that will send requests.

Authentication

Three authentication options, configured on the webhook trigger:

None

Any caller can trigger the workflow. Suitable for testing or when the sending system cannot sign requests.

API Key

The caller passes a key in a configurable HTTP header. The default header is X-API-Key.

POST /api/webhooks/{shortId}
X-API-Key: your-generated-key

The key is generated when the webhook endpoint is created and shown once. Store it securely -- it cannot be retrieved again.

HMAC signature

The caller signs the request body and includes the signature in a header. Rills verifies the signature before processing.

Setting	Default	Options
Algorithm	`sha256`	`sha256`, `sha1`, `sha512`
Signature header	`X-Hub-Signature-256`	Any header name

Signature format: sha256=<hex_digest> (GitHub-compatible). This makes Rills webhook endpoints directly compatible with GitHub webhook deliveries.

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

Payload handling

The request body is parsed as JSON and made available as trigger data in the workflow context. All downstream nodes can access context.trigger to read the payload.

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

// Available in custom code as context.trigger
context.trigger.event    // "order.created"
context.trigger.order_id // "abc-123"

Idempotency

Prevent duplicate workflow executions from retried requests. Configure an idempotency header name (e.g., X-Idempotency-Key) on the webhook endpoint.

When a request includes this header, Rills checks whether a request with the same idempotency key has been processed within the TTL window. Duplicates are rejected.

Setting	Default
TTL	86,400 seconds (24 hours)

The TTL is configurable per webhook endpoint.

Event filtering

Filter incoming requests by event type so only specific events trigger the workflow.

eventTypeField -- A field name in the JSON payload that contains the event type (e.g., type or event).
acceptedEventTypes -- An array of event type values to accept. Payloads with other event types are ignored.

Example: set eventTypeField to event and acceptedEventTypes to ["order.created", "order.updated"]. A payload with { "event": "order.cancelled" } will not trigger the workflow.

Status codes

Responses returned by the webhook endpoint:

Status	Meaning
200	Request accepted, workflow triggered
400	Invalid request (malformed URL or JSON)
401	Authentication failed
404	Webhook endpoint not found
410	Webhook expired or already used (one-time webhooks)
429	Rate limited (retry after 60 seconds)
503	Webhook disabled

Monitoring

Each webhook endpoint tracks operational metrics:

Last triggered -- Timestamp of the most recent request.
Total triggers -- Cumulative request count.
Consecutive failures -- Number of sequential failed triggers. Resets on success.
Last error -- Error message from the most recent failure.

These metrics are available in workspace settings under the webhook endpoint details.

Workflows reference -- Node types, retry policies, and execution lifecycle
Your first workflow -- Step-by-step tutorial including webhook triggers
Integrations -- Connecting external services that can send webhooks