Skip to main content

Webhooks

Overview​

You can utilize webhooks to get notified about events related to your prospects and campaigns. You will receive a notification when a prospect replies, is marked as interested, your campaign has finishes, etc.

All notifications are triggered at the account level. For instance, when you subscribe to the prospect_replied event, you will receive data about replies from prospects across all campaigns associated with your account.

Managing webhook subscription​

To subscribe or unsubscribe from webhooks, send a POST request with the target_url and event specified in the body. You can find detailed instructions here:

Subscription limits​

You can subscribe to the same event up to three times per account, provided that each subscription uses a unique target_url. Attempting to subscribe to the same event more times will result in a 409 response. You can subscribe multiple different events to one target URL.

To review your current subscriptions, use the GET v2/webhooks endpoint.

Error handling​

All webhooks are sent using HTTP POST method. Should the receiving server return an error, for example 500 code response, Woodpecker uses an exponential backoff retry mechanism to attempt delivery of the data.

Multiple subsequent failed delivery attempts may result in unsubscribing a given target_url and event pair. A webhook event will also be automatically unsubscribed if the receiving servers responds with HTTP codes 310 or 410.

Batch delivery​

We use a batching mechanism that groups multiple prospect events into a single webhook payload when they occur within a short time window. Events are grouped only if they share the same event type and target_url. The payload is sent as an array of objects, with each object representing one event or prospect's data. The maximum array size is 100 objects.

Available events​