List Webhook Logs

GET https://api.somossimpay.com.br/v3/webhooks/logs

This API retrieves webhook execution logs for your account. It returns a paginated history of all webhook delivery attempts, including request details, responses, and status codes. Use this endpoint to monitor webhook deliveries and troubleshoot issues.

Endpoint

GET /v3/webhooks/logs

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo

Query Parameters

Parameter	Type	Description	Required or Optional
limit	Integer	Maximum number of results per page. Minimum: 1, Maximum: 100. Default: 20.	optional
transaction_id	String	Filter by transaction end-to-end ID.	optional
type	String	Filter by webhook type. Valid values: CASHIN (cash-in webhooks) or CASHOUT (cash-out webhooks).	optional
filter_start_date	Date	Start date for filtering logs (YYYY-MM-DD format). Filters logs from 00:00:00 of this date.	optional
filter_end_date	Date	End date for filtering logs (YYYY-MM-DD format). Filters logs until 23:59:59 of this date.	optional
cursor_datetime	DateTime	Cursor datetime for pagination (ISO 8601 format). Used together with cursor_id.	optional
cursor_id	Integer	Cursor ID for pagination. Used together with cursor_datetime.	optional
cursor_direction	String	Direction of pagination. Valid values: NEXT, PREVIOUS. Default: NEXT.	optional

Request Examples

List all webhook logs (default pagination):

HTTP

GET /v3/webhooks/logs?limit=20
Authorization: Bearer <access_token>

Filter by transaction ID:

HTTP

GET /v3/webhooks/logs?transaction_id=E123456789012345678901234567890123&limit=20
Authorization: Bearer <access_token>

Filter by webhook type (CASHIN):

HTTP

GET /v3/webhooks/logs?type=CASHIN&limit=50
Authorization: Bearer <access_token>

Filter by date range:

HTTP

GET /v3/webhooks/logs?filter_start_date=2026-05-01&filter_end_date=2026-05-12&limit=20
Authorization: Bearer <access_token>

Navigate to next page using cursor:

HTTP

GET /v3/webhooks/logs?cursor_datetime=2026-05-12T10:30:00Z&cursor_id=98765&cursor_direction=NEXT&limit=20
Authorization: Bearer <access_token>

Response Details

Response

{
  "next": "https://api.somossimpay.com.br/v3/webhooks/logs?cursor_datetime=2026-05-12T10:30:00Z&cursor_id=98765&cursor_direction=NEXT&limit=20",
  "previous": null,
  "results": [
    {
      "id": 98765,
      "url": "https://client.example.com/webhooks/pix",
      "webhook_id": 123,
      "type": "PIX_QR_CODE_CREATED",
      "transaction_id": "E123456789012345678901234567890123",
      "body": "{\"event_type\":\"pix.qrcode.created\",\"data\":{...}}",
      "header": "{\"Content-Type\":\"application/json\",\"X-Signature\":\"...\"}",
      "status_code": 200,
      "response": "{\"success\":true}",
      "created_at": "2026-05-12T08:15:30Z",
      "updated_at": "2026-05-12T08:15:31Z"
    },
    {
      "id": 98764,
      "url": "https://client.example.com/webhooks/pix",
      "webhook_id": 123,
      "type": "PIX_TRANSACTION_CREATED",
      "transaction_id": "E987654321098765432109876543210987",
      "body": "{\"event_type\":\"pix.transaction.created\",\"data\":{...}}",
      "header": "{\"Content-Type\":\"application/json\",\"X-Signature\":\"...\"}",
      "status_code": 500,
      "response": "{\"error\":\"Internal server error\"}",
      "created_at": "2026-05-11T14:20:10Z",
      "updated_at": "2026-05-11T14:20:11Z"
    }
  ]
}

Field	Type	Description
next	String	URL for the next page of results. null when there are no more results.
previous	String	URL for the previous page of results. null when on the first page.
results	Array	Array of webhook log objects.

Results Object Fields

Field	Type	Description
id	Integer	Unique identifier of the webhook log.
url	String	The URL where the webhook was sent. null if not available.
webhook_id	Integer	ID of the webhook configuration that triggered this delivery. null if not available.
type	String	Type of webhook event (e.g., PIX_QR_CODE_CREATED, PIX_TRANSACTION_CREATED). null if not available.
transaction_id	String	End-to-end ID of the associated transaction. null if not available.
body	String	JSON payload that was sent in the webhook request. null if not available.
header	String	Headers that were sent with the webhook request. null if not available.
status_code	Integer	HTTP status code returned by the webhook endpoint. null if delivery failed before receiving response.
response	String	Response body received from the webhook endpoint. null if not available.
created_at	DateTime	Date and time when the webhook was sent.
updated_at	DateTime	Date and time when the log was last updated.

Error Responses

HTTP Code	Error Message	Description
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token.
422	Validation error	Request validation failed. Check that query parameters are in the correct format.

Business Rules

Authentication:

• Requires valid authentication token
• User must be authenticated
• Only webhook logs for your account are returned

Pagination:

• Results are ordered by creation date (newest first)
• Use cursor-based pagination with cursor_datetime, cursor_id, and cursor_direction to navigate through pages
• The limit parameter controls how many results are returned per page (minimum 1, maximum 100)

Filters:

• All filters are optional and can be combined
• Filter by transaction_id to find webhooks related to a specific transaction
• Filter by type to find specific webhook event types (CASHIN or CASHOUT)
• Filter by date range using filter_start_date and filter_end_date to find webhooks within a specific period
• Date filters use your local timezone and include the entire day (00:00:00 to 23:59:59)

Response Status:

• status_code indicates the HTTP response from your webhook endpoint
• Status codes in 2xx range indicate successful delivery
• Status codes in 4xx or 5xx range indicate delivery failures
• null status_code means the webhook endpoint could not be reached