Skip to content

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.

Request body field map
FieldTypeRequiredConstraints
channelstringrequired"webhook" | "email"
profileIdstring | nulloptionalstring or null
webhookobjectoptionalObject with required url field
webhook.urlstringrequired when webhook presenturi
emailobjectoptionalObject with required recipients field
email.recipientsarray<string>required when email present1 <= items <= 10; each item is an email string

Exact captured contract; webhook.url and email.recipients are required when their parent object is present.

Response body field map
FieldTypeRequiredConstraints
successbooleanrequiredBoolean
messagestringrequiredString

Captured 200 and 400 examples are identical; no additional error shape is evidenced.

Response status decision matrix
StatusContent typeHow to handle
200application/jsonRead success and message; proceed to save only if the result indicates the destination is acceptable.
400application/jsonRead 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.

Webhook test request example
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"
    }
  }'
Email test request example
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]"]
    }
  }'
Response body example for 200 and 400
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.channelstring__1Yeskind: schemaValueIn; value: "webhook" | "email"
body#1body.profileIdstring | null__2No
body#1body.profileId[variant1]string__2_type:string
body#1body.profileId[variant2]null__2_type:null
body#1body.webhookobject__3No
body#1body.webhook.urlstring__4YesHTTPS endpoint that receives the service JSON payloadskind: ; value: uri
body#1body.emailobject__5No
body#1body.email.recipientsarray<string>__6Yeskind: ; value: 1 <= items <= 10
body#1body.email.recipients[]string__7kind: ; value: email
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.messagestring__2Yes