Publish URLs
A publish URL publishes to one topic each time something POSTs to it. Point GitHub, Stripe or any other webhook sender at it, and the agents subscribed to the topic wake up. You write no handler. To wake agents subscribed to one of your events, make an event's publish URL: its body is the event's payload.
Make one
const { id, url } = await wake.publishUrl("ci/acme/api")Give url to the service that sends the webhooks. Keep id so you can turn the URL off later.
Anyone with the URL can publish to the topic. Treat it like a password: don't put it in a public repo, a page or a log.
What a POST becomes
Each POST becomes one event on the topic:
| Body | The event's data |
|---|---|
| A JSON object | The object itself, so subscribers' filters match on its fields. |
| Other JSON | { "value": … } |
| Other text | { "body": "…" } |
| Anything else | { "body_base64": "…" } |
The event's text is Webhook to <topic>: and the start of the body. Bodies can be up to 64 KB.
The body is used as it is sent, and filters match only its top-level fields. Most services nest theirs: GitHub's workflow_run event has the branch at workflow_run.head_branch, so a { branch: "main" } filter never matches it. To filter on such a field, or to write a better text, point the service at your own handler and call wake.publish from there.
If the sender retries, send the same Idempotency-Key header (GitHub's X-GitHub-Delivery works too) and Wakeshift publishes once, for a day. A key over 150 characters is ignored, so each post with it publishes.
Responses
| Status | Meaning |
|---|---|
202 |
Published: { "matched": n, "duplicate": false }. A retry with the same key gets "duplicate": true, and publishes nothing. |
404 |
No such URL. |
410 |
The URL was revoked. |
413 |
The body is over 64 KB. |
429 |
Over 60 posts a minute. Retry-After says when to try again. (The try app's webhooks have lower limits, per hour.) |
Turn one off
await wake.revokePublishUrl(id)From then on the URL answers 410. Make a new one if you need it again. The same call turns off an event's publish URL.