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

# Receive Real-Time Event Notifications

> Real-time event notifications and integration with external systems. Receive instant HTTP callbacks when calls complete, fail, or require tool execution.

Get real-time notifications when events happen. Webhooks push HTTP callbacks to your server when calls complete, fail, or need tool execution.

**What you'll learn:** How webhooks work and event types.

***

## How webhooks work

<Steps>
  <Step title="Event occurs">
    Call ends, agent updated, or tool called
  </Step>

  <Step title="Webhook triggered">
    BlackBox constructs HTTP POST with event payload
  </Step>

  <Step title="Delivery attempted">
    Request sent to your configured endpoint
  </Step>

  <Step title="Your endpoint responds">
    Return HTTP 200 to acknowledge
  </Step>
</Steps>

***

## Webhook types

### Event webhooks

Notify about call lifecycle events. Configured in agent's "Webhooks" tab.

| Event                     | Description                   |
| ------------------------- | ----------------------------- |
| `StartWebHookPayload`     | Call initiated or received    |
| `CompletedWebHookPayload` | Call finished with transcript |
| `FailedWebHookPayload`    | Call encountered error        |
| `TransferWebHookPayload`  | Transfer decision requested   |

### Tool webhooks

Execute functions called by the agent during conversations. Configured in agent's "Tools" tab.

<Card title="Tools & Functions" icon="wrench" href="/docs/create/tools-and-functions">
  Complete tool configuration guide
</Card>

***

## Security

* **Use HTTPS** — Encrypt data in transit
* **Respond quickly** — Return HTTP 200 within 30 seconds
* **Handle duplicates** — Webhooks may be retried; use idempotency keys
* **Validate payloads** — Check required fields before processing

### Endpoint requirements

* URL must be publicly accessible
* Cannot use localhost or loopback addresses (127.0.0.1, ::1)

***

## What's next

<CardGroup cols={2}>
  <Card title="Configuring Webhooks" icon="gear" href="/docs/webhooks-and-events/configuring-webhooks">
    Setup guide
  </Card>

  <Card title="Webhook Events" icon="bell" href="/docs/webhooks-and-events/webhook-events">
    Complete event reference
  </Card>

  <Card title="Testing Webhooks" icon="flask-vial" href="/docs/webhooks-and-events/testing-webhooks">
    Testing and debugging
  </Card>
</CardGroup>