Webhook Events Reference
Complete reference for all webhook event types, payloads, and deduplication behavior.
Email event types (LinkedIn, Instagram and WhatsApp reply events are covered in 'Webhooks — Getting Started'):
1) reply.received
Fires when a prospect replies to a campaign email (first reply only).
Payload: prospectId, prospectEmail, campaignId, mailboxId, subject, messageId (the reply's own Message-ID), receivedAt, channel. When the reply names one of your emails it also carries inReplyToMessageId (the messageId of the email it answered — the same value as in email.sent), stepIndex and stepNumber; otherwise those three are left out.
Dedup: One event per prospect per campaign (ever).
2) email.sent
Fires once for every campaign email, when your sending mailbox's server accepts it. That is not yet a delivery confirmation — if the email bounces later you receive email.bounced. Warmup emails and test sends are not included.
Payload: prospectId, prospectEmail, campaignId, campaignName, stepIndex (counts from 0), stepNumber (the "Step N" shown in the app), mailboxId, fromEmail, subject, messageId, sentAt, channel
Dedup: One event per email.
Missed one? GET /api/v1/emails/sent returns the same records (API key with the Campaigns: read permission). Records are kept for as long as the campaign exists, and at least 13 months after a contact finishes it.
3) email.bounced
Fires when an email hard-bounces (permanent delivery failure).
Payload: prospectId, prospectEmail, campaignId, mailboxId, bounceType (hard/soft), bounceReason, bouncedAt
Dedup: One event per prospect per campaign per day.
4) email.unsubscribed
Fires when a prospect clicks the unsubscribe link.
Payload: prospectId, prospectEmail, campaignId, unsubscribedAt
Dedup: One event per prospect per campaign (ever).
5) email.opened
Fires when a prospect opens a campaign email (tracked via invisible pixel).
Payload: prospectId, prospectEmail, campaignId, mailboxId, stepIndex, openedAt
Dedup: One event per prospect per campaign (first open only). Subsequent opens by the same prospect do not trigger additional events.
Note: Some email clients (Apple Mail, Outlook) may auto-load images, causing false opens. Use clicks for more reliable engagement tracking.
6) email.clicked
Fires when a prospect clicks a tracked link in a campaign email.
Payload: prospectId, prospectEmail, campaignId, mailboxId, stepIndex, url, clickedAt
Dedup: One event per unique URL per prospect per day. If a prospect clicks Link A and Link B, you receive two separate events. Clicking the same link twice on the same day fires only once.
7) prospect.suppressed
Fires when a prospect is added to the suppression list (via unsubscribe, bounce, or manual suppression).
Payload: prospectId (optional), email, reason, suppressedAt
Dedup: One event per email per day.
8) limit.hit
Fires when a daily sending limit is reached.
Payload: limitType (daily_mailbox or daily_domain), mailboxId, campaignId, currentValue, limitValue, hitAt
Dedup: One event per limit type per identifier per day.
9) webhook.test
Fires when you send a test event via the API (POST /api/v1/webhooks/:id/test) or by clicking 'Test' in Settings > Webhooks.
Payload: webhookId, timestamp, message
Dedup: None — each test generates a unique event. Used to verify your endpoint is reachable and correctly processing events.
Payload Format (all events):
{
"type": "email.clicked",
"data": {...event-specific fields... },
"timestamp": "2026-03-20T14:30:00.000Z"
}
Headers Included:
- Content-Type: application/json
- X-Warmy-Event-Id: Unique event UUID
- X-Warmy-Event-Type: The event type string
- X-Warmy-Timestamp: Unix timestamp in milliseconds
- X-Warmy-Signature: HMAC-SHA256 signature (t=timestamp,v1=hex)
Subscribing to Events:
- Via UI: Settings > Webhooks > Create Webhook > select events
- Via API: POST /api/v1/webhooks with events array
- Use wildcard '*' via API to subscribe to all events