> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time notifications when events occur in your useSend account

## Overview

Webhooks allow you to receive HTTP POST requests to your server when events occur in useSend, such as when an email is delivered, bounced, or clicked. This enables you to build real-time integrations and automate workflows.

## Setting up webhooks

<Steps>
  <Step title="Create a webhook endpoint">
    Create an endpoint on your server that can receive POST requests. The endpoint must:

    * Accept POST requests with JSON body
    * Return a 2xx status code to acknowledge receipt
    * Respond within 10 seconds
  </Step>

  <Step title="Add webhook in dashboard">
    Go to [Webhooks](https://app.usesend.com/webhooks) in your useSend dashboard and create a new webhook:

    * Enter your endpoint URL
    * Select which events you want to receive
    * Copy the signing secret for verification
  </Step>

  <Step title="Verify webhook signatures">
    Always verify webhook signatures to ensure requests are from useSend. See the [Signature Verification](#signature-verification) section below.
  </Step>
</Steps>

## Event types

### Email events

| Event                     | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| `email.queued`            | Email has been queued for sending                    |
| `email.sent`              | Email has been sent to the recipient's mail server   |
| `email.delivered`         | Email was successfully delivered                     |
| `email.delivery_delayed`  | Email delivery is being retried                      |
| `email.bounced`           | Email bounced (permanent or temporary)               |
| `email.rejected`          | Email was rejected                                   |
| `email.rendering_failure` | Email failed during template rendering               |
| `email.complained`        | Recipient marked email as spam                       |
| `email.failed`            | Email failed to send                                 |
| `email.cancelled`         | Scheduled email was cancelled                        |
| `email.suppressed`        | Email was suppressed (recipient on suppression list) |
| `email.opened`            | Recipient opened the email                           |
| `email.clicked`           | Recipient clicked a link in the email                |

### Contact events

| Event             | Description             |
| ----------------- | ----------------------- |
| `contact.created` | New contact was created |
| `contact.updated` | Contact was updated     |
| `contact.deleted` | Contact was deleted     |

### Domain events

| Event             | Description                   |
| ----------------- | ----------------------------- |
| `domain.created`  | New domain was added          |
| `domain.verified` | Domain verification completed |
| `domain.updated`  | Domain settings were updated  |
| `domain.deleted`  | Domain was deleted            |

## Webhook payload

Each webhook request includes a JSON payload with the following structure. See [Event data details](#event-data-details) for details on the `data` field for each event type.

```json theme={null}
{
  "id": "call_abc123",
  "type": "email.delivered",
  "version": "2026-01-18",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "teamId": 123,
  "data": {
    "id": "email_123",
    "status": "DELIVERED",
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Welcome!",
    "occurredAt": "2024-01-15T10:30:00Z"
  },
  "attempt": 1
}
```

### Payload fields

| Field       | Description                                |
| ----------- | ------------------------------------------ |
| `id`        | Unique identifier for this webhook call    |
| `type`      | The event type (e.g., `email.delivered`)   |
| `version`   | API version for the payload format         |
| `createdAt` | When the event was created                 |
| `teamId`    | Your team ID                               |
| `data`      | Event-specific data (varies by event type) |
| `attempt`   | Delivery attempt number (1-6)              |

## Request headers

Each webhook request includes the following headers:

| Header                | Description                            |
| --------------------- | -------------------------------------- |
| `X-UseSend-Signature` | HMAC-SHA256 signature for verification |
| `X-UseSend-Timestamp` | Unix timestamp in milliseconds         |
| `X-UseSend-Event`     | Event type                             |
| `X-UseSend-Call`      | Unique webhook call ID                 |
| `X-UseSend-Retry`     | `true` if this is a retry attempt      |

## Signature verification

Always verify webhook signatures to ensure requests are authentic. The signature is computed as:

```
HMAC-SHA256(secret, "${timestamp}.${rawBody}")
```

### Using the SDK (Recommended)

<CodeGroup>
  ```bash npm theme={null}
  npm install usesend-js
  ```

  ```bash yarn theme={null}
  yarn add usesend-js
  ```

  ```bash pnpm theme={null}
  pnpm add usesend-js
  ```

  ```bash bun theme={null}
  bun add usesend-js
  ```
</CodeGroup>

### Next.js App Router

```typescript theme={null}
import { UseSend } from "usesend-js";

const usesend = new UseSend("us_your_api_key");
const webhooks = usesend.webhooks(process.env.USESEND_WEBHOOK_SECRET!);

export async function POST(request: Request) {
  try {
    const rawBody = await request.text();
    const event = webhooks.constructEvent(rawBody, {
      headers: request.headers,
    });

    switch (event.type) {
      case "email.delivered":
        console.log("Email delivered to:", event.data.to);
        break;
      case "email.bounced":
        console.log("Email bounced:", event.data.id);
        break;
      case "email.opened":
        console.log("Email opened:", event.data.id);
        break;
    }

    return new Response("ok");
  } catch (error) {
    console.error("Webhook error:", error);
    return new Response((error as Error).message, { status: 400 });
  }
}
```

### Express

```typescript theme={null}
import express from "express";
import { Webhooks } from "usesend-js";

const webhooks = new Webhooks(process.env.USESEND_WEBHOOK_SECRET!);

const app = express();

// Important: Use raw body parser for webhook routes
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = webhooks.constructEvent(req.body, {
      headers: req.headers,
    });

    switch (event.type) {
      case "email.delivered":
        console.log("Email delivered to:", event.data.to);
        break;
      case "email.bounced":
        console.log("Email bounced:", event.data.id);
        break;
    }

    res.status(200).send("ok");
  } catch (error) {
    console.error("Webhook error:", error);
    res.status(400).send((error as Error).message);
  }
});

app.listen(3000);
```

### Verification only

If you only need to verify the signature without parsing:

```typescript theme={null}
const isValid = webhooks.verify(rawBody, { headers: request.headers });

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}
```

### Manual verification

If you prefer to verify manually without the SDK:

```typescript theme={null}
import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(
  secret: string,
  rawBody: string,
  signature: string,
  timestamp: string,
): boolean {
  const expectedSignature = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const expected = Buffer.from(`v1=${expectedSignature}`, "utf8");
  const received = Buffer.from(signature, "utf8");

  if (expected.length !== received.length) {
    return false;
  }

  return timingSafeEqual(expected, received);
}

// Usage
const signature = request.headers.get("X-UseSend-Signature");
const timestamp = request.headers.get("X-UseSend-Timestamp");

const isValid = verifyWebhook(secret, rawBody, signature, timestamp);
```

## Retry behavior

If your endpoint doesn't return a 2xx response, useSend will retry delivery with exponential backoff:

| Attempt | Delay        |
| ------- | ------------ |
| 1       | Immediate    |
| 2       | \~5 seconds  |
| 3       | \~10 seconds |
| 4       | \~20 seconds |
| 5       | \~40 seconds |
| 6       | \~80 seconds |

After 6 failed attempts, the webhook call is marked as failed.

<Warning>
  If your webhook endpoint fails 30 consecutive calls, the webhook will be
  automatically disabled to prevent continued failures. You can re-enable it
  from the dashboard.
</Warning>

## Best practices

<AccordionGroup>
  <Accordion title="Respond quickly">
    Return a 2xx response as soon as possible. Process webhook data
    asynchronously if needed. Requests timeout after 10 seconds.
  </Accordion>

  <Accordion title="Handle duplicates">
    Use the `id` field in the payload to deduplicate events. In rare cases, the
    same event may be delivered more than once.
  </Accordion>

  <Accordion title="Verify signatures">
    Always verify the `X-UseSend-Signature` header to ensure requests are from
    useSend and haven't been tampered with.
  </Accordion>

  <Accordion title="Check timestamps">
    The SDK rejects signatures older than 5 minutes by default. This prevents
    replay attacks.
  </Accordion>

  <Accordion title="Use HTTPS">
    Always use HTTPS endpoints in production to encrypt webhook data in transit.
  </Accordion>
</AccordionGroup>

## Testing webhooks

You can send a test webhook from the dashboard to verify your endpoint is working correctly:

1. Go to [Webhooks](https://app.usesend.com/webhooks)
2. Click on your webhook
3. Click "Send Test" to send a test event

The test event will have type `webhook.test` with the following payload:

```json theme={null}
{
  "test": true,
  "webhookId": "wh_abc123",
  "sentAt": "2024-01-15T10:30:00.000Z"
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook not receiving events">
    * Verify your endpoint URL is correct and publicly accessible - Check that
      your endpoint returns a 2xx status code - Ensure the webhook is set to
      ACTIVE status in the dashboard - Check if the webhook was auto-disabled due
      to consecutive failures
  </Accordion>

  <Accordion title="Signature verification failing">
    * Use the raw request body, not parsed JSON - Ensure you're using the
      correct webhook secret - Check that the timestamp hasn't expired (5 minute
      window) - Verify you're computing the HMAC correctly: `HMAC-SHA256(secret,
          "${timestamp}.${rawBody}")`
  </Accordion>

  <Accordion title="Webhook auto-disabled">
    After 30 consecutive failed calls, webhooks are automatically disabled. Fix
    the issue with your endpoint, then re-enable the webhook from the dashboard.
    The failure counter resets on the next successful delivery.
  </Accordion>
</AccordionGroup>

## Event data details

This section documents the `data` field structure for each event type.

### Email events

Most email events share a common base structure:

```typescript theme={null}
{
  id: string;              // Email ID
  status: string;          // Email status (e.g., "DELIVERED", "BOUNCED")
  from: string;            // Sender email address
  to: string[];            // Recipient email addresses
  occurredAt: string;      // ISO 8601 timestamp
  subject?: string;        // Email subject
  campaignId?: string;     // Campaign ID (if from a campaign)
  contactId?: string;      // Contact ID (if sent to a contact)
  domainId?: number;       // Domain ID
  templateId?: string;     // Template ID (if using a template)
  metadata?: object;       // Custom metadata you attached to the email
}
```

#### email.bounced

Includes additional bounce details:

```typescript theme={null}
{
  // ... base email fields
  bounce: {
    type: "Transient" | "Permanent" | "Undetermined";
    subType: "General" | "NoEmail" | "Suppressed" | "OnAccountSuppressionList"
           | "MailboxFull" | "MessageTooLarge" | "ContentRejected" | "AttachmentRejected";
    message?: string;      // Bounce message from the mail server
  }
}
```

#### email.failed

Includes failure reason:

```typescript theme={null}
{
  // ... base email fields
  failed: {
    reason: string; // Failure reason
  }
}
```

#### email.suppressed

Includes suppression details:

```typescript theme={null}
{
  // ... base email fields
  suppression: {
    type: "Bounce" | "Complaint" | "Manual";
    reason: string;        // Why the email was suppressed
    source?: string;       // Source of the suppression
  }
}
```

#### email.opened

Includes open tracking details:

```typescript theme={null}
{
  // ... base email fields
  open: {
    timestamp: string;     // When the email was opened
    userAgent?: string;    // Browser/client user agent
    ip?: string;           // IP address
    platform?: string;     // Detected platform
  }
}
```

#### email.clicked

Includes click tracking details:

```typescript theme={null}
{
  // ... base email fields
  click: {
    timestamp: string;     // When the link was clicked
    url: string;           // The clicked URL
    userAgent?: string;    // Browser/client user agent
    ip?: string;           // IP address
    platform?: string;     // Detected platform
  }
}
```

### Contact events

All contact events (`contact.created`, `contact.updated`, `contact.deleted`) include:

```typescript theme={null}
{
  id: string;              // Contact ID
  email: string;           // Contact email address
  contactBookId: string;   // Contact book ID
  subscribed: boolean;     // Subscription status
  properties: object;      // Custom properties
  firstName?: string;      // First name
  lastName?: string;       // Last name
  createdAt: string;       // ISO 8601 timestamp
  updatedAt: string;       // ISO 8601 timestamp
}
```

### Domain events

All domain events (`domain.created`, `domain.verified`, `domain.updated`, `domain.deleted`) include:

```typescript theme={null}
{
  id: number;              // Domain ID
  name: string;            // Domain name (e.g., "example.com")
  status: string;          // Domain status
  region: string;          // AWS region
  createdAt: string;       // ISO 8601 timestamp
  updatedAt: string;       // ISO 8601 timestamp
  clickTracking: boolean;  // Click tracking enabled
  openTracking: boolean;   // Open tracking enabled
  subdomain?: string;      // Subdomain for tracking
  dkimStatus?: string;     // DKIM verification status
  spfDetails?: string;     // SPF record details
  dmarcAdded?: boolean;    // DMARC record added
}
```