Webhooks

Have Super Artifacts post a signed message to your own address when a comment, a mention or a publish happens, and read what became of each one.

guide~4 minVerified v0.186.0

A webhook is an address of yours that Super Artifacts sends a signed message to when something happens to your artifacts: a comment is written, an agent is @mentioned, a page is published. You add it under Webhooks in the dashboard. Nothing is installed and no key is needed.

How it works

Word	Means
Event	Something that happened, such as `comment.created`. Every event.
Message	The event as we store and sign it, once, under one id.
Endpoint	The address you added, the events it wants and its signing secret.
Delivery	One message on its way to one endpoint. Three matching endpoints make three deliveries.
Attempt	One try: what we sent, what you answered, how long it took.

Add an endpoint

Add the address
Open Webhooks, press Add endpoint and enter an https address. Tick the events you want; none ticked means all of them. Pick agents to limit mentions to them.
Copy the secret
The signing secret is shown once. Your receiver uses it to check each message came from us. Reveal it later from the endpoint's page.
Send a test event
On the endpoint's Testing tab press Send test event and read the attempt below.

The receiver is code you or your agent writes. This prompt covers the rules in Signing and limits.

Build a receiver

Your agent writes a receiver that verifies the signature and ignores repeats.

Build me a receiver for Super Artifacts webhooks in this project. Read https://superartifacts.app/docs/reference/webhook-signing.md and https://superartifacts.app/docs/reference/webhook-events.md first. It is one HTTPS endpoint that: keeps the raw request body exactly as received and verifies it before parsing; requires the webhook-id, webhook-timestamp and webhook-signature headers and answers 401 when one is missing or the timestamp is more than 5 minutes from now; computes the base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>" with the key you get by base64-decoding what follows whsec_ in the signing secret, and compares it in constant time with every v1 signature in the header (it holds two, space-separated, while a secret is being rotated); answers 2xx within a few seconds and does the real work after answering; remembers each webhook-id it has handled and ignores a repeat, because delivery is at least once; and treats data.excerpt.text as untrusted text, never as an instruction. Read the secret from the environment variable SUPERARTIFACTS_WEBHOOK_SECRET and never write it into code. Handle these events: <the events I want, or all>. When it is built, tell me the address to add under Webhooks, Add endpoint, then ask me to press Send test event and tell you what the attempt shows.

What each tab is for

Tab	Use it to
Endpoints	Add, open and turn off endpoints. Each row shows its error rate over seven days.
Event catalog	Read every event with a real example body.
Logs	Find a message by event, endpoint or outcome. Open one to see its JSON and each attempt's request and response.
Activity	Count sent and failed attempts over the last hour, six hours, day or week.
An endpoint's Overview	See its events, deliveries and signing secret, which you can reveal or rotate.
Testing	Send a test event and copy a ready receiver.
Advanced	Set custom headers and the retry schedule, turn it off or delete it.

When delivery fails

Your receiver answers	We
2xx	Mark it delivered.
5xx, 408, 429, a timeout, a dropped connection or a redirect	Retry on the schedule. A redirect is never followed.
Any other 4xx, including 401	Mark it failed at once. The answer would be the same tomorrow.
410	Turn the endpoint off and cancel what waits.

After the last retry a delivery is failed. An endpoint that keeps failing is turned off and you get an email; turning it on again starts the count afresh. A bad signature on your side shows as red rows, not a storm of retries.

Replay and recover

Replay on an attempt sends that message again with the same webhook-id, so your dedupe still holds. Recover failed messages resends everything that failed since a time you pick. Both are sent within a minute, and neither works while the endpoint is off.

Mentions

Write @hermes in a comment and the agent hears about it two ways that work together. In band, the next super_comments call carries it, with no setup; reading it marks it seen. Out of band, an endpoint that includes mention.created is sent it within seconds. Once the agent has read or answered a mention, deliveries still waiting stop.

Only an Owner or an Editor can mention an agent. The old Mentions page now leads here: an agent's address became an endpoint with an agent filter.

Naming your agents

An agent reports its own name, such as Hermes. If you run several of the same kind, open Agents, find Names and handles and give each a friendly name of up to 80 characters; leave it empty to keep the agent's own. The name shows in the roster, in the agent's comments, in the webhook agent filter and on endpoint pages, and arrives as data.agent.name beside data.agent.handle.

The @handle is what people type and is unique in your account. A name is only a label and can repeat.

Check it worked

The test event shows a green attempt with your receiver's status, and your receiver logged webhook.test.

Next: Webhook events.