@ahpd/webhook

Webhooks for the @ahpd/server daemon. A program outside the host calls a URL, and the call talks to a bot, starts the automation its connector names, or fires the webhook trigger.

Each endpoint is a webhook connector, and names its own vault secrets. A call passes only with the proof its endpoint's scheme names: a bearer token by default, one sender's own signature, a header or query token, or a generic HMAC.

Part of ahpd. The source is in packages/webhook.

Install

ahpd plugin install @ahpd/webhook
ahpd restart

Update, remove and one-run flags such as --plugin are in Plugins.

Options

In the configuration file, with every option set:

{ "plugins": [{ "name": "@ahpd/webhook", "options": { "syncTimeoutSeconds": 10, "maxBodyBytes": 26214400 } }] }

Option	Default	What it does
syncTimeoutSeconds	10	How long a sync call waits for its turn to end, in seconds: GitHub's window. A GitHub endpoint waits at most 10 and a Microsoft Graph one at most 3, the windows those senders give before they count a delivery failed
maxBodyBytes	26214400	The most of a call body the plugin reads, in bytes: 25 MiB, which holds GitHub's 25 MB payload cap. A larger body answers 413

An endpoint

{
  "id": "github",
  "adapter": "webhook",
  "owner": "host",
  "config": {
    "automation": "ci-review",
    "auth": "github",
    "secret": "the webhook secret GitHub holds"
  }
}

Sent as the params of x-ahpd/connectors/put, that connector answers POST /plugins/webhook/github for a GitHub delivery signed with its secret, and a call starts the ci-review automation. The secret is written to the vault, and the record holds { "$secret": "<name>" } in its place. A config that names no automation and no bot fires the webhook trigger instead.

WEBHOOKS.md describes the schemes, one example for each real sender, the event data a run reads, match, and the answers.

Documentation

WEBHOOKS.md	The record, the call and the answers

License

MIT.

What a webhook endpoint is and what it may reach are WEBHOOKS.md.