Test Notification API: Test a Notification Destination Before Saving It
The Test Notification API lets you test notification destination settings before saving them. Send a POST request to /v1/notifications/test with a channel of webhook or email, the matching destination details, and an x-access-key header, then check the success and message fields in the JSON response before you save the destination.
Purpose: test a notification destination before saving it
Use this endpoint when you want to verify a notification destination before saving it. The operation is a single POST to /v1/notifications/test. Choose channel as webhook for a webhook destination or email for an email destination, supply the matching destination object, and include profileId only when you need to scope the test to a profile. The request body is application/json and the response body is application/json for both 200 and 400.
Authorization: x-access-key header
Send the access key in the x-access-key header. The captured contract names the header x-access-key and places it in the header, with the value shown as a token placeholder. Also send Content-Type: application/json so the JSON request body is parsed as intended. The captured contract does not specify the response to a missing or invalid header, so do not assume a successful test result in that case.
Request body field map and worked examples
The request body has four top-level fields. channel is required and must be webhook or email. profileId is optional and may be a string or null. webhook is an optional object; when present, its url field is required and is a string URI for the HTTPS endpoint that receives JSON payloads. email is an optional object; when present, its recipients field is required and is an array of 1 to 10 email strings. See the Request body field map table for the exact types and requiredness, and the Webhook test request example and Email test request example for worked requests using only these evidenced fields.
Response body: 200 and 400 application/json
The response contract lists 200 application/json and 400 application/json. In both cases the captured example body contains success as a required boolean and message as a required string. See the Response body example for the exact captured shape. Because the captured 200 and 400 examples are identical, treat the status code as the primary branch: handle 200 as a completed test response and 400 as a rejected request, then read success and message in either case without assuming additional error fields that were not captured.
Before-saving checklist
Before saving a destination, run through this checklist. First, confirm channel matches the destination you intend to test: webhook with a webhook object, or email with an email object. Second, confirm the nested field is complete: webhook.url for webhook, or email.recipients with 1 to 10 email strings for email. Third, confirm profileId is either omitted, a string, or null, matching the optional string | null type. Fourth, confirm the x-access-key header and Content-Type: application/json are present. Only save the destination after the test returns a 200 response you can act on.
Failure and decision matrix
Use the failure and decision matrix to decide what to fix. A 200 response means the test request was processed under the captured contract; read message for the human-readable result and proceed to save only if success and message indicate the destination is acceptable. A 400 response means the request was rejected; re-check channel, the nested destination field, recipients count, and headers, then retry. Do not invent extra error fields or retry, delivery, or signing behavior that is not in the captured contract.
| Field | Type | Required | Constraints |
|---|---|---|---|
| channel | string | required | "webhook" | "email" |
| profileId | string | null | optional | string or null |
| webhook | object | optional | Object with required url field |
| webhook.url | string | required when webhook present | uri |
| object | optional | Object with required recipients field | |
| email.recipients | array<string> | required when email present | 1 <= items <= 10; each item is an email string |
Exact captured contract; webhook.url and email.recipients are required when their parent object is present.
| Field | Type | Required | Constraints |
|---|---|---|---|
| success | boolean | required | Boolean |
| message | string | required | String |
Captured 200 and 400 examples are identical; no additional error shape is evidenced.
| Status | Content type | How to handle |
|---|---|---|
| 200 | application/json | Read success and message; proceed to save only if the result indicates the destination is acceptable. |
| 400 | application/json | Read success and message; re-check channel, nested destination field, recipients count, and x-access-key header, then retry. |
Status semantics beyond the captured success/message example are not evidenced.
Frequently asked questions
How do I test a notification destination before saving it?
Send POST to /v1/notifications/test with the x-access-key header, Content-Type application/json, a required channel of webhook or email, and the matching destination object. For webhook, include webhook.url. For email, include email.recipients with 1 to 10 email strings. profileId is optional and may be a string or null.
What should I check in the response?
The captured contract lists 200 and 400, both application/json, with the same example shape: success as a boolean and message as a string. Do not assume additional error fields beyond that captured shape. Check the HTTP status first, then read success and message, and correct the request fields listed in the field map before retrying.
Which request fields are required?
channel is required and must be webhook or email. profileId, webhook, and email are optional in the captured schema. webhook.url is required when the webhook object is present, and email.recipients is required when the email object is present. Whether the destination object is conditionally required by channel is not explicitly stated in the captured source, so preserve the captured requiredness and verify against the implementation contract before relying on a stricter rule.
curl -X POST "{{API_BASE_URL}}/v1/notifications/test" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"channel": "webhook",
"webhook": {
"url": "https://example.com/notifications"
}
}'curl -X POST "{{API_BASE_URL}}/v1/notifications/test" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"channel": "email",
"email": {
"recipients": ["[email protected]"]
}
}'{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.channel | string | __1 | Yes | kind: schemaValueIn; value: "webhook" | "email" | |
| body#1 | body.profileId | string | null | __2 | No | ||
| body#1 | body.profileId[variant1] | string | __2_type:string | |||
| body#1 | body.profileId[variant2] | null | __2_type:null | |||
| body#1 | body.webhook | object | __3 | No | ||
| body#1 | body.webhook.url | string | __4 | Yes | HTTPS endpoint that receives the service JSON payloads | kind: ; value: uri |
| body#1 | body.email | object | __5 | No | ||
| body#1 | body.email.recipients | array<string> | __6 | Yes | kind: ; value: 1 <= items <= 10 | |
| body#1 | body.email.recipients[] | string | __7 | kind: ; value: email | ||
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.message | string | __2 | Yes |