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

# Managing Webhooks

> List, create, update, and delete Lettr webhook endpoints from Laravel for delivery, open, click, bounce, and spam events

Webhooks deliver real-time notifications when emails are delivered, opened, clicked, bounced, or marked as spam. Manage your webhook endpoints through the `Lettr` facade.

For the event payload format and signature verification, see [Webhooks](/learn/webhooks/introduction).

```php theme={null}
use Lettr\Laravel\Facades\Lettr;
```

## List Webhooks

```php theme={null}
$webhooks = Lettr::webhooks()->list();

foreach ($webhooks as $webhook) {
    echo $webhook->id;
    echo $webhook->name;
    echo $webhook->url;
    echo $webhook->enabled;
    echo $webhook->authType->value;     // 'none', 'basic', 'oauth2'
    echo $webhook->lastStatus?->value;  // 'success', 'failure', or null

    // null eventTypes = subscribed to all events
    if ($webhook->listensToAllEvents()) {
        echo 'all events';
    } else {
        foreach ($webhook->eventTypes as $eventType) {
            echo $eventType->value;  // 'message.delivery', 'engagement.click', etc.
        }
    }

    // Health check
    if ($webhook->isFailing()) {
        echo "Last failed at: " . $webhook->lastFailureAt;
    }
}
```

<Card title="API Reference" icon="book" href="/api-reference/webhooks/list-webhooks">
  GET /webhooks
</Card>

## Create a Webhook

```php theme={null}
use Lettr\Dto\Webhook\CreateWebhookData;
use Lettr\Enums\WebhookAuthType;
use Lettr\Enums\WebhookEventsMode;
use Lettr\Enums\WebhookEventType;

$webhook = Lettr::webhooks()->create(new CreateWebhookData(
    name: 'Production events',
    url: 'https://example.com/webhooks/lettr',
    authType: WebhookAuthType::None,
    eventsMode: WebhookEventsMode::Selected,
    events: [
        WebhookEventType::MessageDelivery,
        WebhookEventType::MessageBounce,
        WebhookEventType::EngagementClick,
    ],
));

echo $webhook->id;
```

<Note>
  Use `WebhookEventsMode::All` to receive every event type (no `events` array needed), or `WebhookEventsMode::Selected` with an explicit `events` array. For authenticated endpoints, set `authType` to `WebhookAuthType::Basic` or `WebhookAuthType::OAuth2` and supply the matching credentials (`authUsername`/`authPassword` or the `oauth*` fields).
</Note>

<Card title="API Reference" icon="book" href="/api-reference/webhooks/create-webhook">
  POST /webhooks
</Card>

## Get Webhook Details

```php theme={null}
use Lettr\Enums\WebhookEventType;

$webhook = Lettr::webhooks()->get('webhook-id');

echo $webhook->name;
echo $webhook->url;
echo $webhook->lastStatus?->value;
echo $webhook->lastSuccessfulAt;
echo $webhook->lastFailureAt;

// Check if the webhook listens to a specific event
if ($webhook->listensTo(WebhookEventType::MessageBounce)) {
    echo "Webhook receives bounce notifications";
}
```

<Card title="API Reference" icon="book" href="/api-reference/webhooks/get-webhook">
  GET /webhooks/{webhook}
</Card>

## Update a Webhook

All fields are optional — only the ones you set are sent:

```php theme={null}
use Lettr\Dto\Webhook\UpdateWebhookData;
use Lettr\Enums\WebhookEventType;

Lettr::webhooks()->update('webhook-id', new UpdateWebhookData(
    url: 'https://example.com/webhooks/lettr-v2',
    active: false,
    events: [WebhookEventType::MessageDelivery],
));
```

<Card title="API Reference" icon="book" href="/api-reference/webhooks/update-webhook">
  PATCH /webhooks/{webhook}
</Card>

## Delete a Webhook

```php theme={null}
Lettr::webhooks()->delete('webhook-id');
```

<Card title="API Reference" icon="book" href="/api-reference/webhooks/delete-webhook">
  DELETE /webhooks/{webhook}
</Card>

## What's Next

<CardGroup cols={2}>
  <Card title="Webhook Events" icon="bell" href="/learn/webhooks/introduction">
    Event types and payload format
  </Card>

  <Card title="Webhook Authorization" icon="shield-check" href="/learn/webhooks/authorization">
    Verify webhook authenticity
  </Card>
</CardGroup>