# Overview

Webhooks allow you to receive annotation data at external URLs when users interact with annotations. This enables integrations with Slack, Discord, custom backends, CI/CD pipelines, and more.

Configure a webhook URL via the `webhookUrl` prop, and events will be sent automatically when annotations are created, updated, deleted, or submitted.

## Configuration

Add the `webhookUrl` prop to enable webhooks:

```javascript
import { Agentation } from "agentation";

function App() {
  return (
    <> 
      <YourApp />
      <Agentation webhookUrl="https://your-server.com/webhook" />
    </>
  );
}
```

With a webhook URL configured, you have two options: enable Auto-Send to fire events automatically, or click "Send Annotations" in the toolbar manually. When Auto-Send is on, the toolbar button is hidden.

## Events

Webhooks fire for the following events:

- `annotation.add` — New annotation created
- `annotation.delete` — Annotation deleted
- `annotation.update` — Annotation comment edited
- `annotations.clear` — All annotations cleared
- `submit` — "Send Annotations" clicked

## Webhook Payload

All events send a POST request with the following JSON structure:

```json
{
  "event": "annotation.add",
  "timestamp": 1706234567890,
  "url": "https://example.com/dashboard",
  "annotation": {
    "id": "1706234567890",
    "comment": "Button is cut off on mobile",
    "element": "button",
    "elementPath": "body > main > form > button.submit-btn",
    "timestamp": 1706234567890
  }
}
```

### Event-specific payloads

`annotation.add` / `annotation.delete` / `annotation.update`

```json
{
  "event": "annotation.add",
  "timestamp": 1706234567890,
  "url": "https://example.com/page",
  "annotation": { ... }
}
```

`annotations.clear`

```json
{
  "event": "annotations.clear",
  "timestamp": 1706234567890,
  "url": "https://example.com/page",
  "annotations": [ ... ]
}
```

`submit`

```json
{
  "event": "submit",
  "timestamp": 1706234567890,
  "url": "https://example.com/page",
  "output": "# Page Feedback\n\n...",
  "annotations": [ ... ]
}
```

## Combining with Callbacks

You can use webhooks alongside the `onSubmit` and other callback props. Both will fire when events occur:

```javascript
<Agentation
  webhookUrl="https://your-server.com/webhook"
  onSubmit={(output, annotations) => {
    // This fires in addition to the webhook
    console.log("Submitted:", annotations.length, "annotations");
  }}
  onAnnotationAdd={(annotation) => {
    // Track in analytics
    analytics.track("annotation_created");
  }}
/>
```

## Use Cases

### Slack Notifications

```javascript
// Server webhook handler
app.post("/webhook/agentation", async (req, res) => {
  const { event, annotation, url } = req.body;

if (event === "annotation.add") {
    await fetch(process.env.SLACK_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        text: `New annotation on ${url}: "${annotation.comment}"`,
      }),
    });
  }

res.json({ ok: true });
});
```

### GitHub Issue Creation

```javascript
app.post("/webhook/agentation", async (req, res) => {
  const { event, output, annotations } = req.body;

if (event === "submit" && annotations.length > 0) {
    await fetch("https://api.github.com/repos/owner/repo/issues", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        title: `[Feedback] ${annotations.length} annotation(s)`,
        body: output,
        labels: ["feedback"],
      }),
    });
  }

res.json({ ok: true });
});
```

### Real-time Dashboard

```javascript
// Server with WebSocket broadcast
app.post("/webhook/agentation", (req, res) => {
  const { event, annotation, url } = req.body;

// Broadcast to connected dashboard clients
  wss.clients.forEach((client) => {
    client.send(JSON.stringify({
      type: "annotation_event",
      event,
      annotation,
      url,
    }));
  });

res.json({ ok: true });
});
```

## Security Considerations

- **Use HTTPS** — Always use encrypted connections for webhook URLs
- **Validate origin** — Check the request origin if your webhook is public
- **Rate limiting** — Implement rate limits to prevent abuse
- **Sanitize content** — Annotation comments may contain user-generated content; sanitize before rendering

## Testing Webhooks

Tools for testing webhooks during development:

- **webhook.site** — Free public endpoint for testing payloads
- **ngrok** — Expose local server for testing with real URLs
- **RequestBin** — Inspect and debug webhook payloads

### Quick Test Setup

```javascript
// Use webhook.site for testing
<Agentation webhookUrl="https://webhook.site/your-unique-id" />

// Then create annotations and check webhook.site for payloads
```