Create Notification API
The Create Notification API creates an email or webhook notification subscription. Send a POST request to {{API_BASE_URL}}/v1/notifications/ with a channel, at least one event type, and the channel-specific destination details. Use the webhook channel when your application needs to receive structured events, and the email channel when a small set of recipients should be notified directly.
Create Notification API overview with POST {{API_BASE_URL}}/v1/notifications/
The Create Notification API creates an email or webhook notification subscription. Send a POST request to {{API_BASE_URL}}/v1/notifications/ with a channel, at least one event type, and the channel-specific destination details. Use the webhook channel when your application needs to receive structured events, and the email channel when a small set of recipients should be notified directly. The request uses application/json. The worked examples titled Create a webhook notification subscription and Create an email notification subscription show the two channel shapes. Before sending, check that channel is exactly webhook or email, that eventTypes contains at least one supported value, and that the destination object matches the selected channel.
Authorization with x-access-key header
Authenticate every request with the accessKey header named x-access-key. Send the token as the header value, as shown in the worked examples titled Create a webhook notification subscription and Create an email notification subscription. If the header is missing or invalid, do not expect a subscription to be created; fix the header value and retry the same request body. Keep the token out of the JSON body, because the contract places it in the header only.
Request body field map for channel, profileId, eventTypes, onlyScheduledPosts, enabled, webhook, and email
The request body is an application/json object. The required channel field selects delivery as webhook or email. The required eventTypes field is an array of strings with at least one item. Supported event values are post.scheduled, post.published, post.partial, post.failed, account.reauthorization_required, and account.disconnected. The optional profileId field is a string or null and scopes the subscription to a profile when set. The optional onlyScheduledPosts boolean defaults to false; when true, matching notifications are delivered only for posts that were scheduled. The optional enabled boolean defaults to true. For the webhook channel, supply the optional webhook object with a required url string in uri format. For the email channel, supply the optional email object with a required recipients array of email strings containing between 1 and 10 items. The field map titled Request body fields lists each field with its type, requiredness, and constraints. A common failure is sending an empty eventTypes array, an unsupported channel value, or an email object without recipients; correct the field named in the failure matrix titled Validation failure matrix and resend.
Worked examples for webhook and email subscriptions
For a webhook subscription, set channel to webhook and include post.scheduled in eventTypes, as in the example titled Create a webhook notification subscription. Add a webhook object with a url when you need delivery to a specific endpoint. For an email subscription, set channel to email, include one or more supported eventTypes values, and include an email object whose recipients array holds between 1 and 10 email addresses, as in the example titled Create an email notification subscription. In both cases, optionally set profileId to scope the subscription, onlyScheduledPosts to true to limit delivery to scheduled posts, and enabled to false to create the subscription in a disabled state. After sending, check the status code and the notification object in the response before storing the returned id for later management.
Response body for 201 success
A successful creation returns status 201 with an application/json body containing success and a notification object. The notification object includes id, channel, profileId, eventTypes, onlyScheduledPosts, enabled, lastTestAt, lastTestStatus, createdAt, and updatedAt, plus webhook or email when present. The webhook object in the response includes url and secret, and the email object includes recipients. The field map titled 201 response fields lists each response field with its type and requiredness. Treat lastTestAt and lastTestStatus as nullable string fields, and profileId as a nullable string. Store the returned id, and use lastTestStatus together with lastTestAt to judge the most recent test outcome for the subscription.
Error response for 400 application/json
A rejected request returns status 400 with an application/json body containing success and message. The example titled 400 error response shows that shape. Use the failure matrix titled Validation failure matrix to check the documented constraints behind a 400 response: channel must be webhook or email, eventTypes must contain at least one supported value, recipients must contain between 1 and 10 email strings when email is supplied, and webhook url must be a uri string when webhook is supplied. Correct only the invalid field, keep the rest of the body unchanged, and resend. Do not treat a 400 response as a created subscription, because no notification object is returned in that contract.
| Field | Type | Required | Constraints / default |
|---|---|---|---|
| channel | string | required | "webhook" | "email" |
| profileId | string | null | optional | — |
| eventTypes | array<string> | required | 1 <= items; values: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected" |
| onlyScheduledPosts | boolean | optional | Default false; when true, deliver matching notifications only for posts that were scheduled |
| enabled | boolean | optional | Default true |
| webhook | object | optional | — |
| webhook.url | string | required when webhook present | uri format |
| object | optional | — | |
| email.recipients | array<string> | required when email present | 1 <= items <= 10; email format |
Exact source contract; origin modularized as {{API_BASE_URL}}.
| Field | Type | Required | |
|---|---|---|---|
| success | boolean | required | |
| notification | object | required | |
| notification.id | string | required | |
| notification.channel | string | required | "webhook" | "email" |
| notification.profileId | string | null | required | |
| notification.eventTypes | array<string> | required | |
| notification.onlyScheduledPosts | boolean | required | |
| notification.enabled | boolean | required | |
| notification.webhook | object | optional | |
| notification.webhook.url | string | required when webhook present | uri format |
| notification.webhook.secret | string | required when webhook present | |
| notification.email | object | optional | |
| notification.email.recipients | array<string> | required when email present | 1 <= items <= 10; email format |
| notification.lastTestAt | string | null | required | date-time |
| notification.lastTestStatus | string | null | required | |
| notification.createdAt | string | required | date-time |
| notification.updatedAt | string | required | date-time |
Exact source contract for 201 response.
| Field | Type | Required |
|---|---|---|
| success | boolean | required |
| message | string | required |
Exact source contract for 400 response.
| Check | Documented constraint | Fix |
|---|---|---|
| channel | Must be "webhook" or "email" | Set channel to one of the two enum values |
| eventTypes | At least 1 item; each item must be a supported event value | Add at least one supported event such as post.scheduled |
| email.recipients | 1 to 10 email strings when email is supplied | Supply between 1 and 10 valid email addresses |
| webhook.url | URI string when webhook is supplied | Supply a valid URI for webhook.url |
| profileId | String or null when supplied | Send a string or null, or omit the field |
Based only on documented constraints; no invented error codes or messages.
curl -X POST "{{API_BASE_URL}}/v1/notifications/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"channel": "webhook",
"eventTypes": [
"post.scheduled"
]
}'curl -X POST "{{API_BASE_URL}}/v1/notifications/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"channel": "email",
"eventTypes": [
"post.scheduled",
"post.failed"
],
"email": {
"recipients": [
"[email protected]"
]
}
}'{
"success": true,
"notification": {
"id": "string",
"channel": "webhook",
"profileId": "string",
"eventTypes": [
"post.scheduled"
],
"onlyScheduledPosts": true,
"enabled": true,
"webhook": {
"url": "http://example.com",
"secret": "string"
},
"email": {
"recipients": [
"[email protected]"
]
},
"lastTestAt": "2019-08-24T14:15:22Z",
"lastTestStatus": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}{
"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: ; 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.eventTypes | array<string> | __3 | Yes | kind: ; value: 1 <= items | |
| body#1 | body.eventTypes[] | string | __4 | kind: ; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected" | ||
| body#1 | body.onlyScheduledPosts | boolean | __5 | No | When true, deliver matching notifications only for posts that were scheduled. | kind: ; value: false |
| body#1 | body.enabled | boolean | __6 | No | kind: ; value: true | |
| body#1 | body.webhook | object | __7 | No | ||
| body#1 | body.webhook.url | string | __8 | Yes | HTTPS endpoint that receives the service JSON payloads | kind: ; value: uri |
| body#1 | body.email | object | __9 | No | ||
| body#1 | body.email.recipients | array<string> | __10 | Yes | kind: ; value: 1 <= items <= 10 | |
| body#1 | body.email.recipients[] | string | __11 | kind: ; value: email | ||
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.notification | object | __2 | Yes | ||
| response#2 | response.notification.id | string | __3 | Yes | ||
| response#2 | response.notification.channel | string | __4 | Yes | kind: schemaValueIn; value: "webhook" | "email" | |
| response#2 | response.notification.profileId | string | null | __5 | Yes | ||
| response#2 | response.notification.profileId[variant1] | string | __5_type:string | |||
| response#2 | response.notification.profileId[variant2] | null | __5_type:null | |||
| response#2 | response.notification.eventTypes | array<string> | __6 | Yes | ||
| response#2 | response.notification.eventTypes[] | string | __7 | kind: schemaValueIn; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected" | ||
| response#2 | response.notification.onlyScheduledPosts | boolean | __8 | Yes | ||
| response#2 | response.notification.enabled | boolean | __9 | Yes | ||
| response#2 | response.notification.webhook | object | __10 | No | ||
| response#2 | response.notification.webhook.url | string | __11 | Yes | kind: ; value: uri | |
| response#2 | response.notification.webhook.secret | string | __12 | Yes | Webhook signing secret (masked in list responses) | |
| response#2 | response.notification.email | object | __13 | No | ||
| response#2 | response.notification.email.recipients | array<string> | __14 | Yes | kind: ; value: 1 <= items <= 10 | |
| response#2 | response.notification.email.recipients[] | string | __15 | kind: ; value: email | ||
| response#2 | response.notification.lastTestAt | string | null | __16 | Yes | kind: ; value: date-time | |
| response#2 | response.notification.lastTestAt[variant1] | string | __16_type:string | kind: ; value: date-time | ||
| response#2 | response.notification.lastTestAt[variant2] | null | __16_type:null | kind: ; value: date-time | ||
| response#2 | response.notification.lastTestStatus | string | null | __17 | Yes | ||
| response#2 | response.notification.lastTestStatus[variant1] | string | __17_type:string | |||
| response#2 | response.notification.lastTestStatus[variant2] | null | __17_type:null | |||
| response#2 | response.notification.createdAt | string | __18 | Yes | kind: ; value: date-time | |
| response#2 | response.notification.updatedAt | string | __19 | Yes | kind: ; value: date-time | |
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |