Webhook Events Reference

Common Payload Structure

All webhook event payloads share this base structure:

{
  "type": "EventType",
  "createdAt": "2026-04-02T10:00:00Z",
  "messageId": "unique-run-id",
  "recipient": "user@example.com",
  "senderDomain": {
    "domain": "mail.yourdomain.com",
    "id": "sender-domain-id"
  },
  "sendIntegration": {
    "name": "My SendGrid",
    "id": "send-integration-id"
  },
  "esp": "SendGrid",
  "source": "ScheduledEmail",
  "sourceId": "source-id",
  "emailContent": {
    "name": "April Newsletter",
    "id": "email-content-id",
    "template": {
      "name": "Newsletter Template",
      "id": "template-id"
    },
    "fromName": {
      "name": "Company Name",
      "id": "from-name-id"
    },
    "subjectLine": {
      "name": "Check out our latest news",
      "id": "subject-line-id"
    }
  }
}

Common Fields

Event Types

Initiated

Email has been queued for sending.

• Additional fields: none

Submitted

Email has been submitted to the ESP for delivery.

• Additional fields: none

Sent

ESP confirmed the email was delivered to the recipient's mail server.

• Additional fields: none

Paused

Send has been paused (manually or by system).

• Additional fields: none

Canceled

Send has been canceled.

• Additional fields: none

Retry

Email is being retried after a temporary failure.

• Additional fields: none

Failed

Send attempt failed permanently.

• Additional fields:

{
  "type": "Failed",
  "error": {
    "reason": "Authentication failed: invalid API key"
  }
}

SoftBounced

Temporary delivery failure (4xx class). May be retried.

• Additional fields:

{
  "type": "SoftBounced",
  "bounce": {
    "type": "soft",
    "message": "452 Insufficient storage"
  }
}

HardBounced

Permanent delivery failure (5xx class). Address should be suppressed.

• Additional fields:

{
  "type": "HardBounced",
  "bounce": {
    "type": "hard",
    "message": "550 Mailbox not found"
  }
}

Complained

Recipient marked the email as spam.

• Additional fields: none

Suppressed

Email was blocked because the recipient is on a suppression list.

• Additional fields: none

Unsubscribed

Recipient clicked the unsubscribe link.

• Additional fields:

{
  "type": "Unsubscribed",
  "unsubscribe": {
    "reason": "No longer interested"
  }
}

Opened

Recipient opened the email.

• Additional fields:

{
  "type": "Opened",
  "client": {
    "ipAddress": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
  }
}

Clicked

Recipient clicked a link in the email.

• Additional fields:

{
  "type": "Clicked",
  "client": {
    "ipAddress": "203.0.113.42",
    "link": "https://example.com/offer",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
  }
}

Event Summary Table