Webhooks: Real-Time Campaign Event Notifications

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.

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.

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.

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:

{
  "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.

/api-reference/webhooks/list — list your webhooks
/api-reference/webhooks/create — create a new webhook
/api-reference/webhooks/update — update an existing webhook

Getting Started

Concepts

Guides

Api Reference

Webhooks: Real-Time Campaign Event Notifications

Event types

Creating a webhook

Updating and deleting webhooks

Webhook payload

Scoping events

​Event types

​Creating a webhook

​Updating and deleting webhooks

​Webhook payload

​Scoping events

​Related endpoints

Event types

Creating a webhook

Updating and deleting webhooks

Webhook payload

Scoping events

Related endpoints