Ade Webhooks

ADE webhooks

A webhook automation is a doorbell. ADE gives the service a private URL; the service rings it when something happens; ADE checks the request (token, signature, conditions, duplicates) and starts the agent with a prompt filled in from the request. When the person is signed in to ADE, the URL goes through ADE's relay, which holds requests for up to 3 days while their computer is asleep.

Do not build this out of ade automations create --from-file with hand-written trigger JSON, a polling loop, or a tunnel you start yourself. Use ade automations webhook create.

The whole flow

1. Ask or infer three things: which service, what should start a run (conditions), and what the agent should do (prompt). Do not ask about anything with a default below.

2. Create it (one command, URL + rule):

   ade automations webhook create --preset github \
     --name "Triage new GitHub issues" \
     --filter headers.x-github-event=issues --filter body.action=opened \
     --prompt "Triage GitHub issue #{{trigger.body.issue.number}} in {{trigger.body.repository.full_name}}: {{trigger.body.issue.title}}
   
   {{trigger.body.issue.body}}
   
   Reproduce it, find the cause, and propose a fix." \
     --in-this-chat --text

   The output is the URL, numbered paste steps for that service, whether the signing secret is saved, and the conditions in words.

3. Signing secret (when the output says it is missing): never ask the person to paste it into chat. Raise the private secret card:

   # GitHub / anything you configure yourself: ADE can generate it
   ade secrets request GITHUB_WEBHOOK_SECRET --reason "Signs GitHub deliveries to the triage webhook" --generate
   # Stripe / Linear / Sentry give you theirs: the person pastes it
   ade secrets request STRIPE_WEBHOOK_SECRET --reason "Stripe's signing secret (whsec_…) for the payment webhook"

   It blocks until they answer and returns only saved / kept / declined. Say exactly what happened, never more:

   • saved after --generate: the card showed the value once; they copy it into the service's secret field.
   • kept: an existing value is used, and nobody can read it back. The service needs that same value. If they no longer have it, raise the card again with --generate and ask them to choose Replace.
   • declined: the webhook rejects every request until a secret is saved (or recreate it with --no-signature, saying what that means).

4. Hand over the URL and the paste steps from step 2's output, in your own short words. Say the URL is private: anyone with it can ring the doorbell.

5. Prove it works:

   ade automations webhook test <wh-id> --text        # signed like the real service
   ade automations webhook deliveries <wh-id> --text  # outcome + one-sentence reason

   A ran outcome means the whole path works. After the person pastes the URL into the real service, read deliveries again to see its first request.

6. ade chat note "webhook: <service> → <what it does>" and report.

Presets (--preset)

GitHub's own issue/PR events also exist as native triggers (github.issue_opened and so on, through ADE's GitHub App). Prefer a webhook when the person wants a repo ADE's GitHub App is not installed on, a GitHub event the native triggers do not cover, or exact control over the payload.

Flags