Starting a Workflow from Another Service

What It Does

A workflow can start when another service sends it an event, such as GitHub telling you that someone pushed new files to your repository. The starter is called When Another Service Sends an Event. Each workflow that uses it gets an address of its own in your account, and a secret that only the workflow and the sender know. Nothing runs unless the delivery is signed with that secret.

Everything here is the same for every account. The address, the secret, every delivery, and every run stay in your own account.

Setting It Up

1. In the workflow's Build tab, choose Add a Starter, then When another service sends an event.
2. Choose GitHub or Other Service.
3. Save the workflow. The address card appears under What Starts It.
4. Select Make Address. The address and the secret are shown once, each with a Copy button (action workflows.outside.make). Put them in the other service. The secret is never shown again.
5. Turn the workflow on when you are ready. A workflow that is off answers deliveries and drops them, and only a person turns a workflow on. Your own AI assistant can build the workflow, but it is always saved off, and it cannot make the address, see the secret, or turn the address on.

You can Replace Secret at any time (action workflows.outside.replace). The old secret stops working at once, and the address stays the same. Turn Off Address and Turn On Address (actions workflows.outside.turn_off and workflows.outside.turn_on) take effect at once. Recent Deliveries (action workflows.outside.deliveries) lists the time, the service, and what happened to each delivery: Accepted, Ignored, Refused, or Rate Limited. It never shows the body, a file name, or the secret. The address card itself (action workflows.outside.get) never has the secret either.

GitHub

In the repository on GitHub, open Settings, Webhooks, Add webhook. Paste the address, set the content type to application/json, paste the secret, and choose Just the push event.

GitHub signs each delivery with the secret (the X-Hub-Signature-256 header), and GitHub's delivery id is the event id. Name the branches that start a run, such as main. A push to any other branch is answered and dropped.

Each run keeps only these values, and nothing else from the push:

• the repository, the branch, and who pushed
• the commit before and after the push
• the files added, changed, and removed

Later steps read them as What Started It. For the files changed in a push, see Reading GitHub From a Workflow.

Other Services

For any other service, the sender signs the time, a dot, and the raw body with your secret (HMAC-SHA256, as lower case hex) and sends three headers. The standard names are X-MDO-Signature, X-MDO-Event-Id, and X-MDO-Timestamp, and you can name different ones when you add the starter. The timestamp is seconds since 1970.

You choose up to 10 values to keep from the event, written as a name and where it is in the event, like order = order.number. Only text, numbers, and yes or no values are kept, and each run also has the event id and when it arrived.

What Is Refused

A delivery that is refused is answered with 400, starts no run, and keeps nothing but a line in Recent Deliveries:

• no signature, a wrong signature, or a signature made with an old secret
• a body over 1 MB, which is refused before it is read
• for Other Service, a missing or wrong timestamp, one more than 300 seconds old, or one that was not the time that was signed
• a missing event id

A delivery id that was already taken is answered 200 and ignored, so a service that sends it again is not retried forever. Delivery ids are kept for 30 days. A delivery that is not a push, or that is a push to a branch you did not name, is also answered 200 and ignored.

Limits

An address takes 30 deliveries a minute, and your account takes 300 a minute. Past that, the answer is 429 with Retry-After, and the sender's own retry sends it again. Nothing is lost on your side and nothing is started by a delivery that was turned away.

A delivery counts as 1 action only when it starts a run. A refused, repeated, or dropped delivery counts none.

What Is Never Kept

The body of a delivery is read in memory and dropped. It is never logged, and it is never kept in a run, a screen, or an error. The secret is kept sealed in your account and is never returned, shown again, or logged. One account's address, secret, and deliveries can never be read from another account, and an address works only in the account that made it.