Skip to content

Update Notification API

The Update Notification API lets you update a notification subscription by ID. Use PATCH /v1/notifications/{id} to change its profile scope, event types, scheduled-post filter, enabled state, webhook destination, or email recipients, then read the returned notification object to confirm the saved values. This page covers authorization, the required path parameter, every optional request field, and the 200, 400, and 404 responses so you can make a partial update without guessing which fields are accepted.

Update Notification API overview

Update a notification subscription when its delivery scope or destination changes. The operation is PATCH /v1/notifications/{id}, where {id} is replaced with the notification subscription ID you want to change. Send only the fields you intend to modify; every request body field is optional, so a partial update can change a single setting such as enabled or onlyScheduledPosts without resending the whole subscription. After the call, check the returned notification object rather than assuming the change was applied, because the response is the authoritative record of the saved profileId, eventTypes, channel, and delivery settings.

Authorization

Authenticate every request with the x-access-key header. The header name is x-access-key and its value is your access token, shown in the contract as <token>. Include Content-Type: application/json when sending a JSON body. If authorization fails or the token is missing, do not retry the same update blindly; first confirm the header name, spelling, and token value, then resend the PATCH request with the corrected header.

Path Parameters

The path parameter id is a required string and identifies the notification subscription to update. Place the actual subscription ID in the /v1/notifications/{id} path, keeping the method as PATCH and the path structure unchanged. A 404 response indicates the ID did not match an existing subscription under the documented contract, so verify the ID against a list or get operation before repeating the update.

Request Body

The request body is a JSON object with all optional fields. profileId accepts a string or null and controls which profile the subscription is scoped to. eventTypes accepts an array of strings with at least one item, and each item must be one of the documented event values. onlyScheduledPosts is a boolean; when true, matching notifications are delivered only for posts that were scheduled. enabled is a boolean that controls whether the subscription is active. webhook is an object whose url field is required when webhook is present and must be a URI string. email is an object whose recipients field is required when email is present and must contain between 1 and 10 email strings. See the request field map table for the exact requiredness and types, and the worked PATCH example for a complete request using only source-defined fields.

Response Body

A successful update returns 200 application/json with success set to true and a notification object. The notification object always includes id, channel, profileId, eventTypes, onlyScheduledPosts, enabled, lastTestAt, lastTestStatus, createdAt, and updatedAt, while webhook and email are included when applicable to the channel. channel is either webhook or email. profileId can be a string or null, lastTestAt and lastTestStatus can be a string or null, and createdAt and updatedAt are date-time strings. When webhook is present, it contains a required url URI string and a required secret string. When email is present, it contains a required recipients array of 1 to 10 email strings. Use these returned values to verify that profileId, eventTypes, onlyScheduledPosts, enabled, webhook, and recipients match what you intended to save.

Failure checks for 400 and 404

Treat 400 and 404 as distinct failure checks. A 400 application/json response uses the documented success and message shape and signals that the request did not satisfy the contract, so re-check field types, the eventTypes enum, the recipients count, and the webhook url format before retrying. A 404 application/json response uses the same success and message shape and signals that the subscription ID was not found, so confirm the id value first. Do not invent additional error fields beyond the documented shape; log the status code and message, correct the cause, and only then repeat the PATCH request.

Request body field map
FieldRequiredTypeConstraints / notes
profileIdOptionalstring | nullProfile scope for the subscription.
eventTypesOptionalarray<string>1 <= items; each item is "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected".
onlyScheduledPostsOptionalbooleanWhen true, deliver matching notifications only for posts that were scheduled.
enabledOptionalbooleanControls whether the subscription is enabled.
webhookOptionalobjectWebhook delivery settings.
webhook.urlRequired when webhook is presentstringuri format.
emailOptionalobjectEmail delivery settings.
email.recipientsRequired when email is presentarray<string>1 <= items <= 10; each item is an email string.

Exact source contract; all request body fields are optional at the top level.

200 response field map
FieldRequiredTypeConstraints / notes
successRequiredbooleanTop-level response field.
notificationRequiredobjectUpdated notification subscription.
notification.idRequiredstringNotification subscription ID.
notification.channelRequiredstring"webhook" | "email".
notification.profileIdRequiredstring | nullProfile scope, or null.
notification.eventTypesRequiredarray<string>Event values from the documented enum.
notification.onlyScheduledPostsRequiredbooleanScheduled-posts-only filter.
notification.enabledRequiredbooleanEnabled state.
notification.webhookOptionalobjectPresent for webhook channel.
notification.webhook.urlRequired when webhook is presentstringuri format.
notification.webhook.secretRequired when webhook is presentstringWebhook signing secret.
notification.emailOptionalobjectPresent for email channel.
notification.email.recipientsRequired when email is presentarray<string>1 <= items <= 10; each item is an email string.
notification.lastTestAtRequiredstring | nulldate-time or null.
notification.lastTestStatusRequiredstring | nullLast test status, or null.
notification.createdAtRequiredstringdate-time.
notification.updatedAtRequiredstringdate-time.

Exact source contract for the 200 notification object.

Failure matrix for 200, 400, and 404
StatusResponse shapeWhat to check
200 application/jsonsuccess (boolean, required) and notification (object, required)Confirm the returned notification fields match the intended update.
400 application/jsonsuccess (boolean, required) and message (string, required)Re-check field types, eventTypes enum values, recipients count, and webhook url format.
404 application/jsonsuccess (boolean, required) and message (string, required)Verify the id path parameter matches an existing notification subscription.

400 and 404 bodies are documented only as success/message examples; no additional error semantics are invented.

PATCH update notification subscription request
curl -X PATCH "{{API_BASE_URL}}/v1/notifications/{id}" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "profileId": "string",
    "eventTypes": ["post.scheduled", "post.published"],
    "onlyScheduledPosts": true,
    "enabled": true,
    "webhook": {
      "url": "https://example.com/notifications"
    },
    "email": {
      "recipients": ["[email protected]"]
    }
  }'
200 response with updated notification object
{
  "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 and 404 response message shape
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
id#1idstring__0YesNotification subscription ID
body#2bodyobject__0Yes
body#2body.profileIdstring | null__1No
body#2body.profileId[variant1]string__1_type:string
body#2body.profileId[variant2]null__1_type:null
body#2body.eventTypesarray<string>__2Nokind: ; value: 1 <= items
body#2body.eventTypes[]string__3kind: ; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected"
body#2body.onlyScheduledPostsboolean__4NoWhen true, deliver matching notifications only for posts that were scheduled.
body#2body.enabledboolean__5No
body#2body.webhookobject__6No
body#2body.webhook.urlstring__7YesHTTPS endpoint that receives the service JSON payloadskind: ; value: uri
body#2body.emailobject__8No
body#2body.email.recipientsarray<string>__9Yeskind: ; value: 1 <= items <= 10
body#2body.email.recipients[]string__10kind: ; value: email
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.notificationobject__2Yes
response#3response.notification.idstring__3Yes
response#3response.notification.channelstring__4Yeskind: schemaValueIn; value: "webhook" | "email"
response#3response.notification.profileIdstring | null__5Yes
response#3response.notification.profileId[variant1]string__5_type:string
response#3response.notification.profileId[variant2]null__5_type:null
response#3response.notification.eventTypesarray<string>__6Yes
response#3response.notification.eventTypes[]string__7kind: schemaValueIn; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected"
response#3response.notification.onlyScheduledPostsboolean__8Yes
response#3response.notification.enabledboolean__9Yes
response#3response.notification.webhookobject__10No
response#3response.notification.webhook.urlstring__11Yeskind: ; value: uri
response#3response.notification.webhook.secretstring__12YesWebhook signing secret (masked in list responses)
response#3response.notification.emailobject__13No
response#3response.notification.email.recipientsarray<string>__14Yeskind: ; value: 1 <= items <= 10
response#3response.notification.email.recipients[]string__15kind: ; value: email
response#3response.notification.lastTestAtstring | null__16Yeskind: ; value: date-time
response#3response.notification.lastTestAt[variant1]string__16_type:stringkind: ; value: date-time
response#3response.notification.lastTestAt[variant2]null__16_type:nullkind: ; value: date-time
response#3response.notification.lastTestStatusstring | null__17Yes
response#3response.notification.lastTestStatus[variant1]string__17_type:string
response#3response.notification.lastTestStatus[variant2]null__17_type:null
response#3response.notification.createdAtstring__18Yeskind: ; value: date-time
response#3response.notification.updatedAtstring__19Yeskind: ; value: date-time
response#4responseobject__0
response#4response.successboolean__1Yes
response#4response.messagestring__2Yes