Webhooks

Create Webhook

Create a new webhook to receive event notifications at the specified URL.

post/webhooks

Request

  • Base URL: https://app.lettr.com/api
  • URL: https://app.lettr.com/api/webhooks
  • Auth: HTTP bearer

Request body

namestring required

Name of the webhook

urlstring uri required

URL where webhook events will be sent

auth_type'none' | 'basic' | 'oauth2' required

Authentication type for the webhook

auth_usernamestring

Username for basic authentication (required when auth_type is 'basic')

auth_passwordstring

Password for basic authentication (required when auth_type is 'basic')

oauth_client_idstring

OAuth2 client ID (required when auth_type is 'oauth2')

oauth_client_secretstring

OAuth2 client secret (required when auth_type is 'oauth2')

oauth_token_urlstring uri

OAuth2 token URL (required when auth_type is 'oauth2')

events_mode'all' | 'selected' required

Whether to receive all events or only selected ones

eventsstring[]

List of event types to receive (required when events_mode is 'selected'). Fully-prefixed names such as message.delivery are canonical; short names (delivery) and the legacy engagament.* prefix are accepted for backwards compatibility and are normalised to the fully-prefixed form.

Example request

{
  "name": "Order Notifications",
  "url": "https://example.com/webhook",
  "auth_type": "basic",
  "auth_username": "user",
  "auth_password": "secret",
  "events_mode": "selected",
  "events": [
    "message.delivery",
    "message.bounce"
  ]
}

Response

Webhook created successfully

messagestring required

Human-readable response message

Example response

{
  "message": "Webhook created successfully.",
  "data": {
    "id": "webhook-abc123",
    "name": "Order Notifications",
    "url": "https://example.com/webhook",
    "enabled": true,
    "event_types": [
      "message.delivery",
      "message.bounce"
    ],
    "auth_type": "basic",
    "has_auth_credentials": true,
    "last_successful_at": "2024-01-15T10:30:00+00:00",
    "last_status": "success"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.