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

# Getting Started

> Receive real-time notifications for email events

## Overview

Webhooks allow you to receive real-time HTTP notifications when email events occur in your account. When an event happens (such as an email being delivered, bounced, or opened), we'll send a POST request to your configured endpoint with details about the event.

## Setting Up Webhooks

<Steps>
  <Step title="Navigate to Webhooks">
    Log in to the [JetEmail Dashboard](https://dash.jetemail.com) and go to **Dashboard → Webhooks**.
  </Step>

  <Step title="Create a Webhook">
    Click **Create Webhook** and configure:

    * **Name**: A friendly name for your webhook
    * **URL**: The endpoint where you want to receive events
    * **Events**: Select which event types you want to receive
  </Step>

  <Step title="Copy Your Secret">
    After creating the webhook, copy your webhook secret. You'll use this to [verify webhook signatures](/webhooks/security).
  </Step>
</Steps>

## Request Format

When an event occurs, we send a POST request to your webhook URL with the following headers:

| Header                | Description                            |
| --------------------- | -------------------------------------- |
| `Content-Type`        | `application/json`                     |
| `X-Webhook-ID`        | Unique identifier for this event       |
| `X-Webhook-Timestamp` | Unix timestamp when the event was sent |
| `X-Webhook-Signature` | HMAC-SHA256 signature for verification |

## Responding to Webhooks

Your endpoint should respond with an HTTP status code to indicate success or failure:

| Status Code        | Behavior                                |
| ------------------ | --------------------------------------- |
| `2xx`              | Success - the event is acknowledged     |
| `429`              | Rate limited - we'll retry with backoff |
| `5xx`              | Server error - we'll retry with backoff |
| `4xx` (except 429) | Permanent failure - event is discarded  |

<Warning>
  Your endpoint must respond within **10 seconds** or the request will timeout and be retried.
</Warning>

## Retry Strategy

If delivery fails, we'll retry with exponential backoff:

| Attempt | Delay                            |
| ------- | -------------------------------- |
| 1       | Immediate                        |
| 2       | 30 seconds                       |
| 3       | 2 minutes                        |
| 4       | 10 minutes                       |
| 5       | 1 hour                           |
| 6       | 4 hours                          |
| 7+      | Event moved to dead letter queue |

## Filtering Events

You can optionally filter which events trigger your webhook:

* **Outbound events**: Filter by username to only receive events for specific SMTP users
* **Inbound events**: Filter by domain to only receive events for specific domains

Leave filters empty to receive events for all users/domains.