Webhook

Download schema

List all webhooks for the team

GET

https://api.lettermint.co/v1

/webhooks

Bearer

Returns a paginated list of webhooks with filtering options.

List all webhooks for the team › query Parameters

page[size]

integer

Default: 15

cursor

string

Cursor for the next or previous page.

sort

string[]

Enum values:

name

-name

url

-url

created_at

-created_at

Default: ["-created_at"]

filter[project]

string

Filter by project ID

filter[enabled]

boolean

Filter by enabled status

filter[event]

WebhookEvent · enum

Filter by specific event type

Enum values:

message.created

message.sent

message.delivered

message.auto_replied

message.hard_bounced

message.soft_bounced

message.spam_complaint

message.failed

filter[route_id]

string

Filter by route ID

filter[scope]

WebhookScope · enum

Filter by webhook scope

Enum values:

team

project

route

filter[search]

string

Search by webhook name or URL

List all webhooks for the team › Responses

Paginated set of WebhookListData

WebhookListData[] · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

next_cursor

string | null · required

The "cursor" that points to the next set of items.

next_page_url

string | null · uri · required

prev_cursor

string | null · required

The "cursor" that points to the previous set of items.

prev_page_url

string | null · uri · required

GET/webhooks

curl https://api.lettermint.co/v1/webhooks \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "id",
      "scope": "team",
      "project_ids": [
        "string"
      ],
      "route_ids": [
        "string"
      ],
      "route_id": "route_id",
      "name": "name",
      "url": "url",
      "has_basic_auth": true,
      "events": [
        "string"
      ],
      "enabled": true,
      "delivery_mode_filter": "live",
      "last_called_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "path": "path",
  "per_page": 0,
  "next_cursor": "next_cursor",
  "next_page_url": "https://www.example.com/path/to/resource",
  "prev_cursor": "prev_cursor",
  "prev_page_url": "https://www.example.com/path/to/resource"
}

json

application/json

Create a new webhook

POST

https://api.lettermint.co/v1

/webhooks

Bearer

Creates a team, project, or route webhook and generates a secret for signature verification.

Create a new webhook › Request Body

StoreWebhookData

name

string · maxLength: 255 · required

url

string · uri · maxLength: 500 · required

events

WebhookEvent[] · minItems: 1 · required

Enum values:

message.created

message.sent

message.delivered

message.auto_replied

message.hard_bounced

message.soft_bounced

message.spam_complaint

message.failed

enabled

boolean | null

Default: true

include_machine_events

boolean | null

Default: false

project_ids

string[] · maxItems: 1000 · unique

Default: []

route_ids

string[] · maxItems: 1000 · unique

Default: []

route_id

string | null · uuid

Create a new webhook › Responses

Webhook created

The webhook with its signing secret, which is only returned when the secret is created or regenerated.

WebhookSecretResponse

WebhookSecretData · required

message

string · required

Human-readable confirmation

POST/webhooks

curl https://api.lettermint.co/v1/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "url": "https://www.example.com/path/to/resource",
  "events": [
    "message.created"
  ],
  "enabled": true,
  "include_machine_events": false,
  "delivery_mode_filter": "live",
  "scope": "team",
  "project_ids": [],
  "route_ids": [],
  "route_id": "00000000-0000-0000-0000-000000000000",
  "basic_auth": {
    "username": "username",
    "password": "password"
  }
}'

Example Request Body

{
  "name": "name",
  "url": "https://www.example.com/path/to/resource",
  "events": [
    "message.created"
  ],
  "enabled": true,
  "include_machine_events": false,
  "delivery_mode_filter": "live",
  "scope": "team",
  "project_ids": [],
  "route_ids": [],
  "route_id": "00000000-0000-0000-0000-000000000000",
  "basic_auth": {
    "username": "username",
    "password": "password"
  }
}

json

Example Responses

{
  "data": {
    "id": "id",
    "scope": "team",
    "project_ids": [
      "string"
    ],
    "route_ids": [
      "string"
    ],
    "route_id": "route_id",
    "name": "name",
    "url": "url",
    "has_basic_auth": true,
    "events": [
      "string"
    ],
    "enabled": true,
    "include_machine_events": true,
    "delivery_mode_filter": "live",
    "secret": "secret",
    "last_called_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "message": "message"
}

json

application/json

Get webhook details

GET

https://api.lettermint.co/v1

/webhooks/{webhookId}

Bearer

Returns full webhook information including recent deliveries.

Get webhook details › path Parameters

webhookId

string · required

Get webhook details › Responses

WebhookData

WebhookData

id

string · required

scope

WebhookScope · enum · required

Enum values:

team

project

route

project_ids

string[] · required

route_ids

string[] · required

name

string · required

url

string · required

has_basic_auth

boolean · required

events

string[] · required

enabled

boolean · required

include_machine_events

boolean · required

delivery_mode_filter

WebhookDeliveryModeFilter · enum · required

Enum values:

live

sandbox

both

last_called_at

string | null · date-time · required

created_at

string · date-time · required

updated_at

string · date-time · required

Update webhook settings

PUT

https://api.lettermint.co/v1

/webhooks/{webhookId}

Bearer

Updates webhook configuration. Events, URL, name, and enabled status can be modified.

Update webhook settings › path Parameters

webhookId

string · required

Update webhook settings › Request Body

UpdateWebhookData

name

string · maxLength: 255

url

string · uri · maxLength: 500

events

WebhookEvent[] · minItems: 1

Enum values:

message.created

message.sent

message.delivered

message.auto_replied

message.hard_bounced

message.soft_bounced

message.spam_complaint

message.failed

enabled

boolean

include_machine_events

boolean

delivery_mode_filter

WebhookDeliveryModeFilter · enum

Enum values:

live

sandbox

both

scope

WebhookScope · enum

Enum values:

team

project

route

project_ids

string[] · maxItems: 1000 · unique

route_ids

string[] · maxItems: 1000 · unique

route_id

string | null · uuid

Update webhook settings › Responses

Webhook updated

The webhook after a change, with a confirmation message.

WebhookMutationResponse

WebhookData · required

message

string · required

Human-readable confirmation

PUT/webhooks/{webhookId}

curl https://api.lettermint.co/v1/webhooks/:webhookId \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "url": "https://www.example.com/path/to/resource",
  "events": [
    "message.created"
  ],
  "enabled": true,
  "include_machine_events": true,
  "delivery_mode_filter": "live",
  "scope": "team",
  "project_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "route_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "route_id": "00000000-0000-0000-0000-000000000000",
  "basic_auth": {
    "username": "username",
    "password": "password"
  }
}'

Example Request Body

{
  "name": "name",
  "url": "https://www.example.com/path/to/resource",
  "events": [
    "message.created"
  ],
  "enabled": true,
  "include_machine_events": true,
  "delivery_mode_filter": "live",
  "scope": "team",
  "project_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "route_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "route_id": "00000000-0000-0000-0000-000000000000",
  "basic_auth": {
    "username": "username",
    "password": "password"
  }
}

json

Example Responses

{
  "data": {
    "id": "id",
    "scope": "team",
    "project_ids": [
      "string"
    ],
    "route_ids": [
      "string"
    ],
    "route_id": "route_id",
    "name": "name",
    "url": "url",
    "has_basic_auth": true,
    "events": [
      "string"
    ],
    "enabled": true,
    "include_machine_events": true,
    "delivery_mode_filter": "live",
    "last_called_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "message": "message"
}

json

application/json

Delete a webhook

DELETE

https://api.lettermint.co/v1

/webhooks/{webhookId}

Bearer

Permanently removes a webhook and all associated delivery records.

Delete a webhook › path Parameters

webhookId

string · required

Delete a webhook › Responses

Webhook deleted

Confirmation that a request succeeded.

MessageResponse

message

string · required

Human-readable confirmation

Test a webhook by sending a sample payload

POST

https://api.lettermint.co/v1

/webhooks/{webhookId}/test

Bearer

Dispatches a test webhook delivery to verify the endpoint is working correctly.

Test a webhook by sending a sample payload › path Parameters

webhookId

string · required

Test a webhook by sending a sample payload › Responses

Test delivery queued

Confirmation that a test delivery was queued.

TestWebhookResponse

message

string · required

Human-readable confirmation

delivery_id

string · required

The ID of the queued test delivery

Regenerate webhook secret

POST

https://api.lettermint.co/v1

/webhooks/{webhookId}/regenerate-secret

Bearer

Generates a new secret for webhook signature verification. The old secret will be invalidated.

Regenerate webhook secret › path Parameters

webhookId

string · required

Regenerate webhook secret › Responses

Webhook secret regenerated

The webhook with its signing secret, which is only returned when the secret is created or regenerated.

WebhookSecretResponse

WebhookSecretData · required

message

string · required

Human-readable confirmation

Get webhook deliveries

GET

https://api.lettermint.co/v1

/webhooks/{webhookId}/deliveries

Bearer

Returns a paginated list of delivery attempts for a specific webhook.

Get webhook deliveries › path Parameters

webhookId

string · required

Get webhook deliveries › query Parameters

cursor

string

Cursor for the next or previous page.

sort

string[]

Enum values:

created_at

-created_at

attempt_number

-attempt_number

Default: ["-created_at"]

filter[status]

WebhookDeliveryStatus · enum

Filter by delivery status

Enum values:

pending

success

failed

client_error

server_error

timeout

filter[event_type]

string

Filter by event type

filter[from_date]

string

Filter deliveries from this date (Y-m-d format)

filter[to_date]

string

Filter deliveries to this date (Y-m-d format)

Get webhook deliveries › Responses

Paginated set of WebhookDeliveryListData

WebhookDeliveryListData[] · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

next_cursor

string | null · required

The "cursor" that points to the next set of items.

next_page_url

string | null · uri · required

prev_cursor

string | null · required

The "cursor" that points to the previous set of items.

prev_page_url

string | null · uri · required

GET/webhooks/{webhookId}/deliveries

curl https://api.lettermint.co/v1/webhooks/:webhookId/deliveries \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "id",
      "webhook_id": "webhook_id",
      "event_type": "message.created",
      "source_scope": "source_scope",
      "source_project_id": "source_project_id",
      "source_route_id": "source_route_id",
      "status": "pending",
      "sandbox": true,
      "payload_retained": true,
      "attempt_number": 0,
      "http_status_code": 0,
      "duration_ms": 0,
      "delivered_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "next_retry_at": "2024-08-25T15:00:00Z"
    }
  ],
  "path": "path",
  "per_page": 0,
  "next_cursor": "next_cursor",
  "next_page_url": "https://www.example.com/path/to/resource",
  "prev_cursor": "prev_cursor",
  "prev_page_url": "https://www.example.com/path/to/resource"
}

json

application/json

Get a specific webhook delivery

GET

https://api.lettermint.co/v1

/webhooks/{webhookId}/deliveries/{deliveryId}

Bearer

Returns full details of a single delivery attempt including payload and response data.

Get a specific webhook delivery › path Parameters

webhookId

string · required

deliveryId

string · required

Get a specific webhook delivery › Responses

WebhookDeliveryData

WebhookDeliveryData

id

string · required

webhook_id

string · required

event_type

WebhookEvent · enum · required

Enum values:

message.created

message.sent

message.delivered

message.auto_replied

message.hard_bounced

message.soft_bounced

message.spam_complaint

message.failed

source_scope

string | null · required

source_project_id

string | null · required

source_route_id

string | null · required

status

WebhookDeliveryStatus · enum · required

Enum values:

pending

success

failed

client_error

server_error

timeout

sandbox

boolean · required

payload_retained

boolean · required

False when only the event type, message ID and Sandbox flag of the payload are stored, because the message is kept 7 days or less. Such a delivery cannot be retried

attempt_number

integer · required

http_status_code

integer | null · required

duration_ms

integer | null · required

delivered_at

string | null · date-time · required

timestamp

string · date-time · required

next_retry_at

string | null · date-time · required

When the next automatic retry is due. Null when none is scheduled

payload

string[]

Omitted when the user cannot view the delivery's content

response_body

string | null

Omitted when the user cannot view the delivery's content

response_headers

array | null

Omitted when the user cannot view the delivery's content

error_message

string | null

Omitted when the user cannot view the delivery's content

GET/webhooks/{webhookId}/deliveries/{deliveryId}

curl https://api.lettermint.co/v1/webhooks/:webhookId/deliveries/:deliveryId \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "id",
  "webhook_id": "webhook_id",
  "event_type": "message.created",
  "source_scope": "source_scope",
  "source_project_id": "source_project_id",
  "source_route_id": "source_route_id",
  "status": "pending",
  "sandbox": true,
  "payload_retained": true,
  "attempt_number": 0,
  "http_status_code": 0,
  "duration_ms": 0,
  "payload": [
    "string"
  ],
  "response_body": "response_body",
  "response_headers": [
    "string"
  ],
  "error_message": "error_message",
  "delivered_at": "2024-08-25T15:00:00Z",
  "timestamp": "2024-08-25T15:00:00Z",
  "next_retry_at": "2024-08-25T15:00:00Z"
}

json

application/json

Retry a webhook delivery

POST

https://api.lettermint.co/v1

/webhooks/{webhookId}/deliveries/{deliveryId}/retry

Bearer

Sends the original payload of a delivery to the webhook again now. The retry counts as a delivery attempt. If it fails with a retryable error, automatic retries continue. Deliveries about messages kept 7 days or less store only the event type, message ID and Sandbox flag, so they cannot be retried.

Retry a webhook delivery › path Parameters

webhookId

string · required

deliveryId

string · required

Retry a webhook delivery › Responses

Retry queued

Confirmation that a manual retry of a delivery was queued.

RetryWebhookDeliveryResponse

message

string · required

Human-readable confirmation

delivery_id

string · required

The ID of the delivery that is retried

Project Message