Skip to main content

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.

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. 
use Lettr\Laravel\Facades\Lettr;

​
List Webhooks

$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;
    }
}

API Reference

GET /webhooks

​
Create a Webhook

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;
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).

API Reference

POST /webhooks

​
Get Webhook Details

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";
}

API Reference

GET /webhooks/

​
Update a Webhook

All fields are optional — only the ones you set are sent: 
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],
));

API Reference

PATCH /webhooks/

​
Delete a Webhook

Lettr::webhooks()->delete('webhook-id');

API Reference

DELETE /webhooks/

​
What’s Next

Webhook Events

Event types and payload format

Webhook Authorization

Verify webhook authenticity