Webhooks: Start an Automation From Another Service

An automation that starts On a webhook has its own secret link. When a request reaches it, a run starts with the request's body as the first item. Use it to let Stripe, Clerk, Resend, your own app or any service that can send a request start something in BankSync.

Set one up#

1. Add the On a webhook trigger (choose When something happens and search for "webhook", or add it from the library's Starts when group).
2. Under Check the sender, choose how the sender signs its requests, if it does, and pick or create a signing secret. See Webhook signing secrets. A webhook with no secret works, with the limits below.
3. Build the steps that read the request (item, trigger) and act on it.
4. Publish, approve the grant and turn the automation on. The toolbar shows the webhook address once: copy it now into the sending service's settings. Turning the automation on again later keeps the same address.

What the sender sees#

A request to the address is answered at once with 202 Accepted, and the run starts. Each trigger takes up to 300 requests a minute. A request a signing secret refuses — no signature, a signature made with another secret, or one older than the tolerance you set — is answered 401 and starts nothing. A request the sender delivers again, with the same delivery id, is answered 202 and starts nothing twice.

To answer the sender with something of your own, add a Respond to the webhook step: a status code, the kind of answer (JSON or plain text) and a body.

Replacing the address#

Get a new webhook address in the toolbar mints a new link and stops the old one at once; the new one is shown once, like the first. Do it when the link may have leaked or when a sender is retired. Scripts and agents can do the same (rotate_automation_webhooks, banksync automations webhooks rotate, for one trigger or all of them), and every rotation is recorded.

What a webhook run may do#

What a webhook sends is untrusted: anyone can send it. That has two consequences in the builder:

• A step that cannot be undone (deleting rows in a mirror sync, sending mail, a bulk delete) downstream of a webhook that does not verify its sender needs an Approval step in front of it. The builder lists it in To do, and the run refuses the step the same way.
• No step takes its target from the request: which table to write, which mailbox to send from, which automation to call must be a fixed value, a picker, a bound resource, a config value or the run's inputs — never item.tableId.

With a signing secret, requests whose signature checks out are treated as coming from the sender you named, and the first rule no longer applies. The second always does.

Credential headers the sender adds are not passed into the run, and the sender's network headers are dropped.

Testing#

More → Settings → Test data holds a sample request for the trigger; Test runs the draft on it without sending or writing anything. A real request to the address of an automation that is off starts nothing.

Webhooks the other way round#

To have BankSync send a webhook when a feed runs — rather than start an automation from one — use the webhook destination of a feed. See the Webhooks integration guide and the webhook payload reference.