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

Add an address under Webhooks to receive signed messages when someone comments, mentions an agent or publishes. No installation or API 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
Press Add endpoint, enter an https address and select events; none means all. Pick agents to filter mentions.
Copy the secret
Copy the signing secret to your receiver. You can reveal it again on the endpoint page.
Send a test event
Under Testing, press Send test event and read its attempt.

Write a receiver using Signing and limits, or copy this prompt.

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, delivery fails. Repeated failures disable the endpoint and trigger an email. Turning it on resets the count.

Replay and recover

Replay resends one message with the same webhook-id. Recover failed messages resends failures since a chosen time. Both send within a minute; neither works while the endpoint is off.

Mentions

An @hermes mention reaches the next super_comments call and endpoints subscribed to mention.created. Reading or answering it stops waiting deliveries.

Owners and Editors can mention agents. The old Mentions page redirects here.

Naming your agents

Under Agents → Names and handles, give each agent a name of up to 80 characters; empty keeps its reported name. It appears in comments, filters and endpoints, and as data.agent.name beside data.agent.handle.

Handles are unique in your account; names can repeat.

Check it worked

Look for a green attempt and webhook.test in your receiver's log.

Next: Webhook events.

Connect Hermes Agent

Choose Hermes Agent under Add endpoint. Paste the public origin reaching Hermes's webhook listener (usually port 8644), exposed through HTTPS. Its dashboard address alone cannot receive events.

Save, then Copy setup prompt into Hermes. It contains the signing secret; keep it private. Saving the route needs no restart. Enable a stopped listener yourself in Hermes's Webhooks settings; that restarts the gateway and may interrupt work.

Mentions default on. Optional human comments and read-only publish summaries exclude agent replies and republishing. Answers go in the source thread through connected MCP tools. Recopy setup after changing events or rotating the secret.

Send test event reporting “Hermes received your test” means HTTP 202 acceptance, not model completion. Check the source thread. The prompt flags settings needing attention, including a ten-request-per-minute authenticated route cap. Hermes may deduplicate replays.