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

# Webhooks

> Send real-time event data from Winnerr to external services via webhooks

Webhooks (`/settings/webhooks`) lets you push Winnerr events to any external URL in real time — so your other tools can react to what happens in your CRM automatically.

## How webhooks work

When a specified event occurs in Winnerr (e.g., a new contact is created), Winnerr sends an HTTP POST request to your endpoint URL with a JSON payload describing the event.

Your endpoint must respond with a `200 OK` within 10 seconds. If it times out or returns an error, Winnerr will retry up to 3 times with exponential backoff.

## Creating a webhook

1. Click **Add Webhook**
2. Enter the destination **URL** (must be publicly accessible HTTPS)
3. Choose which **events** to subscribe to
4. Optionally add a **secret** for signature verification
5. Click **Save** — the webhook is live immediately

## Available events

| Category      | Events                                                                              |
| ------------- | ----------------------------------------------------------------------------------- |
| **Contacts**  | `contact.created`, `contact.updated`, `contact.deleted`                             |
| **Deals**     | `deal.created`, `deal.stage_changed`, `deal.closed_won`, `deal.closed_lost`         |
| **Calls**     | `call.completed`, `call.missed`, `call.recording_ready`, `call.transcription_ready` |
| **Tasks**     | `task.created`, `task.completed`, `task.overdue`                                    |
| **Emails**    | `email.received`, `email.opened`, `email.bounced`                                   |
| **Workflows** | `workflow.triggered`, `workflow.step_completed`, `workflow.failed`                  |

## Payload format

Every webhook payload follows this structure:

```json theme={null}
{
  "event": "contact.created",
  "timestamp": "2025-01-15T14:23:00Z",
  "organizationId": "org_abc123",
  "data": {
    "id": "contact_xyz",
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
}
```

## Verifying signatures

If you set a **webhook secret**, Winnerr signs every request with an HMAC-SHA256 signature in the `X-Winnerr-Signature` header. Verify it in your endpoint:

```javascript theme={null}
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}
```

## Logs & debugging

The **Logs** tab shows the last 500 webhook delivery attempts — request body, response status, response body, and delivery time. Use this when debugging a new integration.

Manually replay any failed delivery from the logs view.