Webhook Events Reference
Complete reference for all webhook event types, payloads, and deduplication behavior.
8 Event Types Available:
1) reply.received
Fires when a prospect replies to a campaign email (first reply only).
Payload: prospectId, prospectEmail, campaignId, mailboxId, subject, messageId, receivedAt
Dedup: One event per prospect per campaign (ever).
2) 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.
3) email.unsubscribed
Fires when a prospect clicks the unsubscribe link.
Payload: prospectId, prospectEmail, campaignId, unsubscribedAt
Dedup: One event per prospect per campaign (ever).
4) 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.
5) 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.
6) 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.
7) 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.
8) 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