# 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.

Kind: guide · ~2 min · Verified v0.237.0 · Next: [Collect signatures](https://pr-2197-stg.superartifacts.app/docs/signatures.md)

## Goal

Notify your own receiver when an artifact event happens.

## What you'll have

An HTTPS endpoint receiving signed messages, with delivery attempts in **Webhooks → Logs**.

## Needs

A signed-in account, permission to manage your endpoints and a reachable HTTPS receiver. Your receiver must verify signatures, ignore repeated message ids and treat event text as untrusted input. Super Artifacts delivers events; your harness runs the agent.

## Prompt

**Build a receiver.** Your agent builds a receiver that verifies signatures and ignores repeats.

```prompt
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.
```

```mermaid
%% hand-drawn: public/docs/diagrams/webhook-delivery.svg is a still drawing; this is its text twin.
flowchart LR
  E["Event<br/>a comment, a publish"] --> M["Message<br/>stored once, signed"]
  M --> DA["Delivery to endpoint A"]
  M --> DB["Delivery to endpoint B"]
  DA --> A1(["attempt 1: 2xx"])
  DB --> B1(["attempt 1: 500"]) --> B2(["attempt 2: 500"]) --> B3(["attempt 3: 2xx"])
```

## Steps

### How it works

An event creates one stored **message**. Each matching **endpoint** gets a **delivery**. Each send is an **attempt**; delivery can repeat.

### Add an endpoint

1. Choose **Add endpoint**, enter an HTTPS address and select events; selecting none subscribes to all. Filter mentions by agent when needed.
2. Copy its signing secret into your receiver's environment. Follow [Signing and limits](https://pr-2197-stg.superartifacts.app/docs/reference/webhook-signing.md). The dashboard can reveal or rotate it.
3. Choose **Send test event**, then inspect the attempt and your receiver's log.

### What each tab is for

**Endpoints** manages addresses; **Event catalog** describes events; **Logs** shows messages and attempts; **Activity** summarizes delivery. An endpoint's Overview, Testing and Advanced controls manage its secret, tests, headers and retries.

### When delivery fails

A 2xx succeeds. Server errors, 408, 429, network failures and redirects retry; redirects are never followed. Other 4xx fail immediately. A 410 disables the endpoint. Repeated failures can disable it and send email.

### Replay and recover

**Replay** resends a message with the same `webhook-id`. **Recover failed messages** selects failures since a time. Enable a disabled endpoint before recovery. Do not assume a replay will run your agent twice.

### Mentions

Mentions reach `super_comments` and `mention.created` subscriptions. Reading or answering stops waiting mention deliveries. Eligibility depends on comment access, agent consent and routing.

### Naming your agents

Rename under **Agents → Connected agents** with the pencil and **Save**. Names can be up to 80 characters. The handle follows the name; collisions add a number. See [agent controls](https://pr-2197-stg.superartifacts.app/docs/agents.md).

### Connect Hermes Agent

Choose the Hermes preset and enter the public HTTPS origin reaching its webhook listener, not its dashboard. Save and paste **Copy setup prompt** into Hermes; it contains a secret. A stopped listener needs enabling in Hermes. A 202 test response proves acceptance, not model completion.

## Check it worked

Find a successful attempt and `webhook.test` in your receiver's log.

## If not

Inspect the response and signature verification before replaying.

## Variations

`super_webhooks` manages endpoints; `agent: me` targets the calling agent. Artifact [triggers](https://pr-2197-stg.superartifacts.app/docs/agents.md#variations) use `trigger.fired`.

## Next

[Webhook events](https://pr-2197-stg.superartifacts.app/docs/reference/webhook-events.md).
