Poll for inbound webhooks (CLI fallback)

GET

/v1/inbound-endpoints/{id}/listen

• Production

Polling fallback for the CLI tool when a WebSocket connection to the streaming service is unavailable. Returns inbound messages received after the after cursor, ordered by UUIDv7 (time-ordered).

Only available for cli-mode endpoints. Returns 400 if the endpoint is in forward mode.

Up to 50 messages are returned per request. Use next_cursor from the response meta to paginate through additional messages.

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Inbound endpoint identifier (UUIDv7)

Example

01935abc-def0-7123-4567-890abcdef012

Query Parameters

after

string format: uuid

Cursor for pagination. Only messages received after this message ID (UUIDv7, time-ordered) are returned. Omit to start from the earliest available message.

Example

01935abc-def0-7123-4567-890abcdef012

Responses

200

Messages retrieved successfully

Response from the CLI polling endpoint. Contains an array of inbound messages with their full payload and headers. Use next_cursor to paginate through additional messages.

object

data

required

Array<object>

object

message_id

required

Unique inbound message identifier (UUIDv7)

string format: uuid

Example

01935abc-def0-7123-4567-890abcdef012

content_type

required

Content-Type of the original inbound payload

string

Example

application/json

headers

required

HTTP headers from the original inbound request

object

key

additional properties

string

Example

{
  "X-Stripe-Signature": "t=1234,v1=abc...",
  "Content-Type": "application/json"
}

size_bytes

required

Payload size in bytes

integer

Example

512

received_at

required

When the inbound message was received

string format: date-time

Example

2026-03-20T10:30:00Z

body

Webhook payload body. JSON payloads are embedded directly as objects. Non-JSON payloads are base64-encoded strings (check body_encoding to distinguish). Omitted when the payload fetcher is not configured or the S3 key is missing.

body_encoding

Present only when body is base64-encoded (non-JSON payloads). Omitted for JSON payloads. Use this field to determine whether body is a raw JSON object or a base64-encoded string.

string

Allowed values: base64

Example

base64

body_error

Present only when the payload could not be fetched from storage. When set, body and body_encoding are omitted.

string

Allowed values: payload_unavailable

Example

payload_unavailable

meta

required

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

next_cursor

Cursor for the next page of results. Pass as the after query parameter to fetch subsequent messages. Null when the response data array is empty (no messages available after the cursor).

string format: uuid

nullable

Example

01935abc-def0-7123-4567-890abcdef099

Example

{
  "data": [
    {
      "message_id": "01935abc-def0-7123-4567-890abcdef012",
      "content_type": "application/json",
      "headers": {
        "X-Stripe-Signature": "t=1234,v1=abc...",
        "Content-Type": "application/json"
      },
      "size_bytes": 512,
      "received_at": "2026-03-20T10:30:00Z",
      "body": {
        "type": "checkout.session.completed",
        "id": "cs_test_abc123"
      }
    },
    {
      "message_id": "01935abc-def0-7123-4567-890abcdef099",
      "content_type": "application/xml",
      "headers": {
        "Content-Type": "application/xml"
      },
      "size_bytes": 1024,
      "received_at": "2026-03-20T10:31:00Z",
      "body": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...",
      "body_encoding": "base64"
    }
  ],
  "meta": {
    "request_id": "req_xyz123",
    "next_cursor": "01935abc-def0-7123-4567-890abcdef099"
  }
}

400

Invalid request

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Examples

Endpoint not found

{
  "error": {
    "code": "ENDPOINT_NOT_FOUND",
    "message": "endpoint not found"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Invalid endpoint ID format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "endpoint_id must be in format ep_xxx"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Invalid payload

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "payload must be valid JSON"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Invalid headers

{
  "error": {
    "code": "INVALID_HEADERS",
    "message": "header 'Host' is forbidden and cannot be overridden"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

401

Unauthorized - Invalid or missing API key

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

404

Resource not found

object

error

object

code

Machine-readable error code

string

Example

INVALID_REQUEST

message

Human-readable error message

string

Example

endpoint must be a valid HTTPS URL

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

req_xyz123

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Message not found"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}