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 client.webhooks resource manages your endpoints. For the event payload format and signature verification, see Webhooks.

​
List Webhooks

const { data, error } = await client.webhooks.list();

if (!error) {
  for (const webhook of data.webhooks) {
    console.log(webhook.id);
    console.log(webhook.name);
    console.log(webhook.url);
    console.log(webhook.enabled);
    console.log(webhook.auth_type);    // "none" | "basic" | "oauth2"
    console.log(webhook.last_status);  // last delivery status, or null

    // event_types is null when subscribed to all events
    if (webhook.event_types === null) {
      console.log("all events");
    } else {
      for (const event of webhook.event_types) {
        console.log(event); // "message.delivery", "engagement.click", ...
      }
    }
  }
}

API Reference

GET /webhooks

​
Create a Webhook

const { data, error } = await client.webhooks.create({
  name: "Production events",
  url: "https://example.com/webhooks/lettr",
  auth_type: "none",
  events_mode: "selected",
  events: ["message.delivery", "message.bounce", "engagement.click"],
});

if (!error) console.log(data.id);
Use events_mode: "all" to receive every event type (no events array needed), or events_mode: "selected" with an explicit events array. For authenticated endpoints set auth_type to "basic" or "oauth2" and supply the matching credentials (auth_username/auth_password or the oauth_* fields).

API Reference

POST /webhooks

​
Get a Webhook

const { data, error } = await client.webhooks.get("webhook-id");

if (!error) {
  console.log(data.name, data.url);
  console.log(data.last_successful_at);
  console.log(data.last_failure_at);
}

API Reference

GET /webhooks/

​
Update a Webhook

All fields are optional — only the ones you set are sent: 
await client.webhooks.update("webhook-id", {
  url: "https://example.com/webhooks/lettr-v2",
  active: false,
  events: ["message.delivery"],
});

API Reference

PATCH /webhooks/

​
Delete a Webhook

const { error } = await client.webhooks.delete("webhook-id");

API Reference

DELETE /webhooks/

​
What’s Next

Webhook Events

Event types and payload format

Webhook Authorization

Verify webhook authenticity