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

# Webhooks

> Receive real-time notifications when events occur in your MINDBLIX account.

## Overview

Webhooks allow your application to receive HTTP callbacks when specific events occur, such as agent execution completion or workflow failures.

***

## Register a Webhook

```bash theme={null}
curl -X POST https://api.mindblix.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/mindblix",
    "events": ["agent.execution.completed", "workflow.run.failed"],
    "secret": "whsec_your_signing_secret"
  }'
```

***

## Event Types

| Event | Description |
| - | - |
| `agent.created` | A new agent was created |
| `agent.execution.started` | An agent started executing |
| `agent.execution.completed` | An agent finished executing |
| `agent.execution.failed` | An agent execution failed |
| `workflow.run.started` | A workflow run started |
| `workflow.run.completed` | A workflow run completed |
| `workflow.run.failed` | A workflow run failed |
| `integration.connected` | An integration was connected |

***

## Webhook Payload

```json theme={null}
{
  "id": "evt_abc123",
  "type": "agent.execution.completed",
  "created_at": "2026-03-04T10:00:00Z",
  "data": {
    "agent_id": "agent_xyz",
    "execution_id": "exec_789",
    "status": "completed",
    "output": { ... }
  }
}
```

***

## Verifying Signatures

Always verify webhook signatures to ensure authenticity:

```python theme={null}
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)
```

> [!WARNING]
>
> Always verify webhook signatures. Without verification, an attacker could send fake webhook events to your endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.