> ## 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.

# POST /api/v1/webhooks — Register a Webhook

> Register a URL to receive HTTP POST notifications for ReachOwl campaign events. Optionally scope deliveries to a single campaign with campaign_id.

Webhooks let your application react in real time to ReachOwl campaign events, such as when a contact accepts a friend request or replies to a message. Register an HTTPS endpoint and choose which events to receive.

<ParamField body="url" type="string" required>
  The HTTPS endpoint that ReachOwl will POST event payloads to.
</ParamField>

<ParamField body="events" type="array" required>
  Array of event type strings to subscribe to. Available values:

  * `contact-is-sent-a-friend-request`
  * `contact-accept-your-friend-request`
  * `contact-is-sent-a-message`
  * `contact-reply-to-your-message`
  * `contact-failed-process`
</ParamField>

<ParamField body="campaign_id" type="integer">
  Scope this webhook to a specific campaign. Omit to receive events from all campaigns.
</ParamField>

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

A successful request returns the created webhook object with its `id`. Use this `id` to update or delete the webhook later.

<Tip>
  Use HTTPS endpoints in production. ReachOwl cannot guarantee delivery to plain HTTP URLs.
</Tip>

To see the full list of available event types, call `GET /api/v1/events` before creating your subscription.