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

# Webhooks: Real-Time Campaign Event Notifications

> ReachOwl sends HTTP POST requests to your endpoint when campaign events fire, such as friend requests sent or messages replied to.

Webhooks let you receive real-time notifications when important events happen in your campaigns. Instead of polling the API for updates, you provide a URL and ReachOwl sends an HTTP POST request to that URL every time a subscribed event occurs. This page lists the available events, how to subscribe, and what the payload looks like.

## Event types

ReachOwl supports five webhook event types:

| Event                                | Description                                                                        |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| `contact-is-sent-a-friend-request`   | A friend request was sent to a contact by a campaign.                              |
| `contact-accept-your-friend-request` | A contact accepted the friend request sent by your campaign.                       |
| `contact-is-sent-a-message`          | A message was delivered to a contact.                                              |
| `contact-reply-to-your-message`      | A contact replied to a message sent by your campaign.                              |
| `contact-failed-process`             | ReachOwl could not process the contact because of an error or platform limitation. |

## Creating a webhook

Subscribe to events by creating a webhook with `POST /api/v1/webhooks`. You must provide a `url` and an `events` array. You can also restrict the webhook to a single campaign by including an optional `campaign_id`.

```bash theme={null}
curl -X POST "{{baseUrl}}/api/v1/webhooks" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/reachowl",
    "events": [
      "contact-is-sent-a-friend-request",
      "contact-reply-to-your-message"
    ],
    "campaign_id": 42
  }'
```

## Updating and deleting webhooks

Change an existing webhook by sending a `PUT` request to `/api/v1/webhooks/{id}` with the updated fields.

```bash theme={null}
curl -X PUT "{{baseUrl}}/api/v1/webhooks/7" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["contact-failed-process"]
  }'
```

Remove a webhook entirely with a `DELETE` request.

```bash theme={null}
curl -X DELETE "{{baseUrl}}/api/v1/webhooks/7" \
  -H "Authorization: Bearer {{token}}"
```

## Webhook payload

When an event fires, ReachOwl sends a JSON payload to your URL. The payload includes the event name, the campaign that triggered it, and the contact involved.

| Field                 | Type    | Description                                 |
| --------------------- | ------- | ------------------------------------------- |
| `event`               | string  | The event type that triggered the webhook.  |
| `campaign_id`         | integer | The campaign associated with the event.     |
| `contact.id`          | integer | The ReachOwl contact ID.                    |
| `contact.name`        | string  | The contact's display name.                 |
| `contact.platform_id` | string  | The contact's platform-specific identifier. |
| `contact.bio`         | string  | The contact's bio text.                     |

Example payload:

```json theme={null}
{
  "event": "contact-reply-to-your-message",
  "campaign_id": 42,
  "contact": {
    "id": 123,
    "name": "Jane Doe",
    "platform_id": "987654321",
    "bio": "Marketing lead at Example Co"
  }
}
```

## Scoping events

If you manage many campaigns, filter webhook traffic by setting `campaign_id` when you create the webhook. This ensures you only receive events for that campaign.

## Related endpoints

* [`/api-reference/webhooks/list`](/api-reference/webhooks/list) — list your webhooks
* [`/api-reference/webhooks/create`](/api-reference/webhooks/create) — create a new webhook
* [`/api-reference/webhooks/update`](/api-reference/webhooks/update) — update an existing webhook