Webhooks & Scheduling

Trigger workflows automatically — from external HTTP events via webhooks or on a recurring cadence via cron schedules.

Webhook Triggers

A webhook trigger starts a workflow when an external system sends an HTTP POST request to a unique URL. The request body becomes the trigger output data, accessible in all downstream nodes.

Setting Up a Webhook

1

Create or open a workflow

In the workflow editor, set the trigger type to Webhook.
2

Copy the webhook URL

The editor generates a unique URL for this workflow. Click the copy icon to grab it. The URL format is: https://app.a91i.com/api/v1/webhooks/{workflowId}
3

Configure the external service

Paste the URL into the external service's webhook settings. For example, in GitHub's repository settings under Webhooks, or in Stripe's webhook endpoints.
4

Enable HMAC verification (recommended)

Set an HMAC secret in the webhook configuration. Share the same secret with the external service so A91I can verify request authenticity.

HMAC Security

HMAC (Hash-based Message Authentication Code) verification ensures that webhook requests come from a trusted source. When enabled:

  • A91I computes an HMAC-SHA256 hash of the request body using your shared secret.
  • It compares the computed hash against the X-Hub-Signature-256 header sent by the caller.
  • If the signatures do not match, the request is rejected with a 401 Unauthorized response.
Signature verification
// The external service computes:
HMAC-SHA256(body, secret) → signature

// It sends the request with:
POST /api/v1/webhooks/{workflowId}
X-Hub-Signature-256: sha256={signature}
Content-Type: application/json

{...body...}

// A91I verifies the signature before executing the workflow.

Always use HMAC in production

Without HMAC verification, anyone who discovers your webhook URL can trigger the workflow with arbitrary data. Always enable it for production workflows.

Testing Webhooks

The webhook configuration panel includes a Test button that sends a sample payload to the webhook URL. You can also test with curl:

Testing with curl
curl -X POST https://app.a91i.com/api/v1/webhooks/{workflowId} \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"message": "Hello from curl"}}'

Webhook Event Log

The webhook panel maintains a log of recent invocations. Each entry shows:

  • Timestamp — when the request was received.
  • Status — whether the signature was valid and the workflow was triggered.
  • Request headers — full HTTP headers for debugging.
  • Request body — the payload that was sent.
  • Response — the HTTP status code returned to the caller.

Use the event log to debug issues like missing signatures, malformed payloads, or unexpected data formats.

Schedule Triggers

A schedule trigger runs the workflow on a recurring cadence defined by a cron expression. This is ideal for periodic tasks that do not depend on external events.

Cron Expressions

A91I uses standard 5-field cron syntax:

Cron format
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *
ExpressionMeaning
*/15 * * * *Every 15 minutes
0 9 * * *Every day at 9:00 AM
0 9 * * 1-5Weekdays at 9:00 AM
0 0 1 * *First day of every month at midnight
0 */6 * * *Every 6 hours
30 17 * * 5Every Friday at 5:30 PM

Timezone

Set the timezone in which the cron expression is evaluated. For example, 0 9 * * * with timezone America/New_York runs at 9:00 AM Eastern, regardless of the server's local time.

Enabling & Disabling

Toggle the schedule on or off without modifying the cron expression. When disabled, the workflow still exists and can be triggered manually, but the scheduler will not start it automatically.

Human-Readable Description

The editor shows a plain-English description below the cron field, such as "Every weekday at 9:00 AM EST" or "Every 15 minutes." This helps verify the expression matches your intent.

Best Practices

  • Use HMAC for all production webhooks. No exceptions.
  • Set reasonable schedules — a 1-minute schedule with expensive API calls can exhaust rate limits and inflate costs.
  • Monitor the first few scheduled executions after activating a workflow to catch timing issues.
  • Use the webhook event log to debug integration issues before blaming the workflow logic.
  • Rotate HMAC secrets periodically. Click Regenerate in the webhook settings, then update the external service.