Skip to content

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.

Request body fields
FieldTypeRequiredConstraints / default
channelstringrequired"webhook" | "email"
profileIdstring | nulloptional—
eventTypesarray<string>required1 <= items; values: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected"
onlyScheduledPostsbooleanoptionalDefault false; when true, deliver matching notifications only for posts that were scheduled
enabledbooleanoptionalDefault true
webhookobjectoptional—
webhook.urlstringrequired when webhook presenturi format
emailobjectoptional—
email.recipientsarray<string>required when email present1 <= items <= 10; email format

Exact source contract; origin modularized as {{API_BASE_URL}}.

201 response fields
FieldTypeRequired
successbooleanrequired
notificationobjectrequired
notification.idstringrequired
notification.channelstringrequired"webhook" | "email"
notification.profileIdstring | nullrequired
notification.eventTypesarray<string>required
notification.onlyScheduledPostsbooleanrequired
notification.enabledbooleanrequired
notification.webhookobjectoptional
notification.webhook.urlstringrequired when webhook presenturi format
notification.webhook.secretstringrequired when webhook present
notification.emailobjectoptional
notification.email.recipientsarray<string>required when email present1 <= items <= 10; email format
notification.lastTestAtstring | nullrequireddate-time
notification.lastTestStatusstring | nullrequired
notification.createdAtstringrequireddate-time
notification.updatedAtstringrequireddate-time

Exact source contract for 201 response.

400 response fields
FieldTypeRequired
successbooleanrequired
messagestringrequired

Exact source contract for 400 response.

Validation failure matrix
CheckDocumented constraintFix
channelMust be "webhook" or "email"Set channel to one of the two enum values
eventTypesAt least 1 item; each item must be a supported event valueAdd at least one supported event such as post.scheduled
email.recipients1 to 10 email strings when email is suppliedSupply between 1 and 10 valid email addresses
webhook.urlURI string when webhook is suppliedSupply a valid URI for webhook.url
profileIdString or null when suppliedSend a string or null, or omit the field

Based only on documented constraints; no invented error codes or messages.

Create a webhook notification subscription
curl -X POST "{{API_BASE_URL}}/v1/notifications/" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "channel": "webhook",
    "eventTypes": [
      "post.scheduled"
    ]
  }'
Create an email notification subscription
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]"
      ]
    }
  }'
201 success response
{
  "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"
  }
}
400 error response
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.channelstring__1Yeskind: ; 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.eventTypesarray<string>__3Yeskind: ; value: 1 <= items
body#1body.eventTypes[]string__4kind: ; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected"
body#1body.onlyScheduledPostsboolean__5NoWhen true, deliver matching notifications only for posts that were scheduled.kind: ; value: false
body#1body.enabledboolean__6Nokind: ; value: true
body#1body.webhookobject__7No
body#1body.webhook.urlstring__8YesHTTPS endpoint that receives the service JSON payloadskind: ; value: uri
body#1body.emailobject__9No
body#1body.email.recipientsarray<string>__10Yeskind: ; value: 1 <= items <= 10
body#1body.email.recipients[]string__11kind: ; value: email
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.notificationobject__2Yes
response#2response.notification.idstring__3Yes
response#2response.notification.channelstring__4Yeskind: schemaValueIn; value: "webhook" | "email"
response#2response.notification.profileIdstring | null__5Yes
response#2response.notification.profileId[variant1]string__5_type:string
response#2response.notification.profileId[variant2]null__5_type:null
response#2response.notification.eventTypesarray<string>__6Yes
response#2response.notification.eventTypes[]string__7kind: schemaValueIn; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected"
response#2response.notification.onlyScheduledPostsboolean__8Yes
response#2response.notification.enabledboolean__9Yes
response#2response.notification.webhookobject__10No
response#2response.notification.webhook.urlstring__11Yeskind: ; value: uri
response#2response.notification.webhook.secretstring__12YesWebhook signing secret (masked in list responses)
response#2response.notification.emailobject__13No
response#2response.notification.email.recipientsarray<string>__14Yeskind: ; value: 1 <= items <= 10
response#2response.notification.email.recipients[]string__15kind: ; value: email
response#2response.notification.lastTestAtstring | null__16Yeskind: ; value: date-time
response#2response.notification.lastTestAt[variant1]string__16_type:stringkind: ; value: date-time
response#2response.notification.lastTestAt[variant2]null__16_type:nullkind: ; value: date-time
response#2response.notification.lastTestStatusstring | null__17Yes
response#2response.notification.lastTestStatus[variant1]string__17_type:string
response#2response.notification.lastTestStatus[variant2]null__17_type:null
response#2response.notification.createdAtstring__18Yeskind: ; value: date-time
response#2response.notification.updatedAtstring__19Yeskind: ; value: date-time
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes