> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time data from external services via webhook endpoints.

## What Are Webhooks?

Webhooks let you receive real-time data from external services. Instead of polling for updates, services push data to your agntdata webhook endpoint, which stores it for later retrieval.

```mermaid theme={null}
sequenceDiagram
    participant Service as External Service
    participant Webhook as agntdata Webhook
    participant App as Your Application / Agent

    Service->>Webhook: POST /webhooks/ingest/:hookId
    Webhook->>Webhook: Store delivery
    App->>Webhook: GET /v1/webhook-endpoints/deliveries (or dashboard)
    Webhook->>App: Return stored payloads
    App->>Webhook: POST /v1/webhook-endpoints/deliveries/:id/ack
```

## Use Cases

<CardGroup cols={2}>
  <Card title="CRM Notifications" icon="bell">
    Receive notifications when leads are updated in your CRM.
  </Card>

  <Card title="E-commerce Events" icon="cart-shopping">
    Get notified about orders, refunds, and inventory changes.
  </Card>

  <Card title="CI/CD Pipelines" icon="code-branch">
    Receive build and deployment notifications.
  </Card>

  <Card title="Social Monitoring" icon="bullhorn">
    Get alerts when tracked accounts post new content.
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Create an Endpoint">
    Create a webhook endpoint in the agntdata dashboard. Each endpoint gets a unique URL.
  </Step>

  <Step title="Configure External Service">
    Point your external service's webhook settings to your agntdata endpoint URL.
  </Step>

  <Step title="Receive Deliveries">
    When the external service sends data, agntdata stores it as a "delivery".
  </Step>

  <Step title="Process Deliveries">
    Fetch deliveries from the dashboard or programmatically via `GET /v1/webhook-endpoints/deliveries` using your API key, then acknowledge them once processed.
  </Step>
</Steps>

## Endpoint URL Format

Each webhook endpoint has a unique URL:

```
https://api.agntdata.dev/webhooks/ingest/{hookId}
```

Example:

```
https://api.agntdata.dev/webhooks/ingest/9f3c8a1e-7b25-4f2d-9a88-2c1e7c34a5b1
```

The `hookId` is the endpoint's unique identifier returned when you create
the endpoint.

## Why Use agntdata Webhooks?

<AccordionGroup>
  <Accordion title="No Server Required">
    You don't need to run a server to receive webhooks. agntdata stores deliveries until you're ready to process them.
  </Accordion>

  <Accordion title="Reliable Storage">
    Deliveries are stored reliably and won't be lost if your application is temporarily down.
  </Accordion>

  <Accordion title="Unified Inbox">
    Collect webhooks from multiple services in one place. View and manage them from the dashboard.
  </Accordion>

  <Accordion title="Replay and Debug">
    View the raw payload of any delivery. Useful for debugging integration issues.
  </Accordion>
</AccordionGroup>

## Dashboard Features

The webhook dashboard provides:

* **Endpoint Management** — Create, view, and delete endpoints
* **Delivery History** — View all received webhook payloads
* **Payload Inspection** — Examine headers and body of each delivery
* **Acknowledgment** — Mark deliveries as processed

## Limits

| Limit               | Value   |
| ------------------- | ------- |
| Payload size        | 1 MB    |
| Deliveries per page | 100 max |

<Note>
  Endpoint names must be 3-50 characters, lowercase alphanumeric with hyphens, and start/end with alphanumeric characters.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Endpoints" icon="plus" href="/webhooks/endpoints">
    Learn how to create and manage webhook endpoints.
  </Card>

  <Card title="Receive Webhooks" icon="inbox" href="/webhooks/receiving">
    Understand webhook payload format and handling.
  </Card>

  <Card title="Managing Deliveries" icon="list-check" href="/webhooks/deliveries">
    Fetch, paginate, and acknowledge deliveries via the API.
  </Card>
</CardGroup>