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. The $lettr->webhooks() service manages your webhook endpoints programmatically. For the event payload format and signature verification, see Webhooks.

​
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;

// Subscribe to specific events
$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;
echo $webhook->url;
Use WebhookEventsMode::All to receive every event type (no events array needed), or WebhookEventsMode::Selected with an explicit events array for a subset. For authenticated endpoints, set authType to WebhookAuthType::Basic or WebhookAuthType::OAuth2 and supply the matching credential fields (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;

$webhook = $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