> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Test Event
> Fire a real, signed test delivery of a sample payload to a registered webhook
Enqueues a real, HMAC-signed test delivery of a realistic sample payload to a webhook's registered URL. The delivery is shaped exactly like a production event and carries `"test": true` in the envelope, so it never mixes with your real events. The webhook must belong to your upstream entity. Use [List Webhooks](/api-reference/v1/webhooks/list-webhooks) to find the `webhookId`.
## Path Parameters
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | ----------------------------------------------------------- |
| **`webhookId`** | string | Yes | Unique identifier of the webhook to test (MongoDB ObjectId) |
## Request Body
| Field | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| **`scenario`** | string | No | Scenario key to sample. Must be a valid key for the webhook's type. Omit to use the type default. |
### Scenario keys by webhook type
| Webhook type | Scenario keys (default first) |
| -------------------------------------------- | --------------------------------------------------------------- |
| `AGENT_COMPLIANCE_STATUS_CHANGE` | `COMPLIANT`, `NOT_COMPLIANT` |
| `DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE` | `COMPLIANT`, `NOT_COMPLIANT` |
| `DOWNSTREAM_ENTITY_CREATED` | `child`, `root` |
| `DOWNSTREAM_ENTITY_DELETED` | `archived`, `removed` |
| `DOWNSTREAM_ENTITY_UPDATED` | `legalName`, `branchName` |
| `AML_OFAC_CHECK_STATUS_CHANGE` | `clear`, `hit` |
| `ENTITY_COMPLIANCE_DATA_SYNCHRONIZED` | `success`, `NIPR error` |
| `PRODUCER_AGREEMENT_EXECUTED` | `executed` |
| `SURPLUS_LINES_FILING_STATUS_CHANGE` | `in progress`, `ready to file`, `filed`, `completed`, `on hold` |
| `SURPLUS_LINES_FILING_ACTION_REQUIRED` | `waiting customer input` |
```bash theme={null}
# Default scenario for the webhook's type
POST /v1/webhooks/6650a1b2c3d4e5f6a7b8c9d0/test
# A specific surplus lines filing status
POST /v1/webhooks/6650a1b2c3d4e5f6a7b8c9d0/test
{ "scenario": "filed" }
```
## Response Shape
All successful responses are wrapped in the standard response envelope. See [Request/Response Conventions](/guides/request-response).
```json theme={null}
{
"statusCode": 200,
"data": {
"scenario": "filed",
"webhookType": "SURPLUS_LINES_FILING_STATUS_CHANGE"
},
"timestamp": "2025-06-01T12:05:00.000Z"
}
```
### Response Fields
| Field | Type | Description |
| ------------- | ------ | ---------------------------------------------------------------------------------- |
| `scenario` | string | The scenario key that was delivered (the resolved default when none was requested) |
| `webhookType` | string | Event type of the webhook the test was delivered to |
The response confirms the delivery was enqueued. The actual signed POST arrives at your registered URL moments later. Inspect the delivery history in the Turris Web App to see the outcome.
## Error Scenarios
### Bad Request (400)
Returned when `webhookId` is not a valid MongoDB ObjectId, or `scenario` is not a valid key for the webhook's type.
```json theme={null}
{
"statusCode": 400,
"errorType": "validation_error",
"errorMessage": ["Invalid scenario 'bogus' for webhook type SURPLUS_LINES_FILING_STATUS_CHANGE"],
"requestId": "dev-abc123",
"timestamp": "2025-06-01T12:00:00.000Z"
}
```
### Unauthorized (401)
Missing or invalid authentication token. See [Authentication](/authentication).
### Webhook Not Found (404)
Returned when the webhook does not exist or belongs to a different upstream entity.
```json theme={null}
{
"statusCode": 404,
"errorType": "not_found",
"errorMessage": ["Webhook 6650a1b2c3d4e5f6a7b8c9d0 not found"],
"requestId": "dev-abc123",
"timestamp": "2025-06-01T12:00:00.000Z"
}
```
### Too Many Requests (429)
Returned when you exceed the test-send rate limit. Space out your test calls and retry.
## OpenAPI
````yaml openapi/v1.json POST /v1/webhooks/{webhookId}/test
openapi: 3.0.0
info:
title: Turris Public API
description: API for managing insurance compliance data
version: 1.0.0
contact: {}
servers:
- url: https://public.api.live.turrisfi.com
description: Production
- url: https://public.api.sandbox.turrisfi.com
description: Sandbox
security: []
tags: []
paths:
/v1/webhooks/{webhookId}/test:
post:
tags:
- webhooks
operationId: WebhooksController_testWebhook_v1
parameters:
- name: webhookId
required: true
in: path
description: Unique identifier of the webhook to test
schema:
example: 6650a1b2c3d4e5f6a7b8c9d0
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestWebhookDto'
responses:
'200':
description: >-
A real signed test event was enqueued for delivery to the webhook
URL
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/WebhookTestResponse'
requestId:
type: string
description: Unique request identifier
example: dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8
timestamp:
type: string
description: Response timestamp
example: '2025-11-12T20:49:03.293Z'
required:
- data
- requestId
- timestamp
'400':
description: Invalid webhookId format or invalid scenario
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'401':
description: Invalid or missing auth token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'404':
description: Webhook not found or belongs to a different upstream entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseDto'
components:
schemas:
TestWebhookDto:
type: object
properties:
scenario:
type: string
description: >-
Scenario key to sample. Must be a valid key for the webhook type
(see the webhook type reference). Omit to use the type default.
example: filed
WebhookTestResponse:
type: object
properties:
scenario:
type: string
description: >-
Scenario key that was delivered (the resolved default when none was
requested)
example: filed
webhookType:
type: string
description: Event type of the webhook the test was delivered to
enum:
- AGENT_COMPLIANCE_STATUS_CHANGE
- AGENT_LICENSE_EXPIRED
- AGENT_LICENSE_EXPIRING
- AGENT_REGULATORY_ACTION_ADDED
- AGENT_REGULATORY_ACTION_UPDATED
- AML_OFAC_CHECK_STATUS_CHANGE
- DOWNSTREAM_ENTITY_COMPLIANCE_STATUS_CHANGE
- DOWNSTREAM_ENTITY_CREATED
- DOWNSTREAM_ENTITY_DELETED
- DOWNSTREAM_ENTITY_LICENSE_EXPIRED
- DOWNSTREAM_ENTITY_LICENSE_EXPIRING
- DOWNSTREAM_ENTITY_REGULATORY_ACTION_ADDED
- DOWNSTREAM_ENTITY_REGULATORY_ACTION_UPDATED
- DOWNSTREAM_ENTITY_UPDATED
- ENTITY_COMPLIANCE_DATA_SYNCHRONIZED
- PRODUCER_AGREEMENT_EXECUTED
- SURPLUS_LINES_FILING_STATUS_CHANGE
- SURPLUS_LINES_FILING_ACTION_REQUIRED
example: SURPLUS_LINES_FILING_STATUS_CHANGE
required:
- scenario
- webhookType
ErrorResponseDto:
type: object
properties:
statusCode:
type: number
description: HTTP status code
requestId:
type: string
description: Unique request identifier for debugging
errorType:
type: string
description: >-
Machine-readable error classification. Branch on this rather than on
`errorMessage`, which is prose and may change. Authentication
failures returned by our identity provider are forwarded verbatim,
so a 401 can carry a code outside this list; treat an unrecognised
value as a generic failure of its HTTP status.
enum:
- conflict
- contact_not_authorized
- document_exceeds_page_limit
- downstream_entity_member_exists
- duplicate_external_id_error
- duplicate_member_email
- duplicate_producer_code_error
- forbidden
- gateway_timeout
- inactive_email
- internal_server_error
- invalid_email
- invalid_email_for_invites
- invalid_organization_category
- invalid_organization_slug
- invalid_phone_number
- invalid_token
- invite_limit_reached
- jwt_invalid
- m2m_client_not_found
- not_found
- organization_already_exists
- organization_slug_already_used
- payment_required
- producer_agreement_required
- product_feature_subscription_required
- service_unavailable
- session_authorization_error
- some_custom_error_string
- throttled
- too_many_requests
- unauthorized
- unauthorized_client
- unexpected_400_stytch_error
- unexpected_403_stytch_error
- unexpected_404_stytch_error
- unexpected_error
- unexpected_stytch_error
- unprocessable_entity
- validation_error
example: validation_error
errorMessage:
description: Array of error messages
type: array
items:
type: string
timestamp:
type: string
description: ISO timestamp when the error occurred
details:
type: object
description: Additional error context
required:
- statusCode
- requestId
- errorType
- errorMessage
- timestamp
````
## Related topics
- [List Webhooks](/api-reference/v1/webhooks/list-webhooks.md)
- [Support and Contact Information](/guides/support.md)
- [Environments](/guides/environments.md)