Webhooks

Webhook event reference

Konvox sends a POST request to your registered endpoint every time a subscribed event fires. Use webhooks to sync data to your CRM, trigger Slack notifications, or build custom automation.

How webhooks work

Register an endpoint in Settings > Webhooks and select the events you want. When an event fires, Konvox sends a POST request with a JSON body to your URL within seconds. Your endpoint should return HTTP 200. Konvox retries failed deliveries up to 3 times with exponential backoff.

Request format

POST https://your-app.com/hooks/konvox
Content-Type: application/json

{
  "event": "contact.replied",
  "timestamp": "2026-05-20T14:32:00.000Z",
  "companyId": "clxyz123...",
  "data": {
    // event-specific payload
  }
}

ⓘ

Always respond within 10 seconds. If your handler does heavy processing, acknowledge the webhook immediately and process async. Timeouts count as failures and trigger retries.

Testing webhooks

Use the Send test button in Settings > Webhooks to fire a sample payload to your endpoint. You can also use a tool like webhook.site during development to inspect the raw payloads.

Contact events

contact.replied

A contact replied to an outbound email or LinkedIn message. The enrollment state is updated to replied.

Field	Type	Description
`contactId`	string	ID of the contact who replied
`channel`	string	`email` or `linkedin`
`subject`	string	Email subject (email channel only)
`campaignId`	string	Campaign that generated this reply, or null
`enrollmentId`	string	Enrollment ID, or null if unattributed

{
  "event": "contact.replied",
  "data": {
    "contactId": "clxyz789",
    "channel": "email",
    "subject": "Re: Quick question about your team",
    "campaignId": "clcmp456",
    "enrollmentId": "clenr123"
  }
}

Enrollment events

enrollment.created

A contact was enrolled in a campaign. The sequence will start on the next scheduled run.

Field	Type	Description
`enrollmentId`	string	Enrollment record ID
`contactId`	string	Contact ID
`campaignId`	string	Campaign ID

enrollment.unsubscribed

A contact opted out. Triggered when an opt-out keyword is detected in a reply, or when the contact's status is manually set to unsubscribed. All active enrollments for that contact are paused.

Field	Type	Description
`enrollmentId`	string	Enrollment that triggered the opt-out
`contactId`	string	Contact ID
`campaignId`	string	Campaign ID
`reason`	string	`opt_out_keyword` or `manual`

{
  "event": "enrollment.unsubscribed",
  "data": {
    "enrollmentId": "clenr123",
    "contactId": "clxyz789",
    "campaignId": "clcmp456",
    "reason": "opt_out_keyword"
  }
}

enrollment.completed

A contact finished the last step of a campaign without replying or opting out.

Field	Type	Description
`enrollmentId`	string	Enrollment record ID
`contactId`	string	Contact ID
`campaignId`	string	Campaign ID

All event names

Use these strings when registering webhook subscriptions via the API.

Event	When it fires
`contact.replied`	A contact replies on any channel
`enrollment.created`	A contact is added to a campaign
`enrollment.unsubscribed`	A contact opts out
`enrollment.completed`	A contact finishes all campaign steps
`message.approved`	An AI-generated message is approved
`message.rejected`	A message is rejected and removed from the queue

Retry policy

If your endpoint returns a non-2xx status or times out, Konvox retries up to 3 times:

Retry 1: 1 minute after the first failure
Retry 2: 5 minutes after retry 1
Retry 3: 30 minutes after retry 2

After 3 failed attempts the delivery is marked as failed. The webhook endpoint stays active and will receive future events. You can check delivery history in Settings > Webhooks.

✓

Make your webhook handler idempotent. Retries can send the same event twice. Use the enrollmentId or contactId as a deduplication key.