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.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| profileId | Optional | string | null | Profile scope for the subscription. |
| eventTypes | Optional | array<string> | 1 <= items; each item is "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected". |
| onlyScheduledPosts | Optional | boolean | When true, deliver matching notifications only for posts that were scheduled. |
| enabled | Optional | boolean | Controls whether the subscription is enabled. |
| webhook | Optional | object | Webhook delivery settings. |
| webhook.url | Required when webhook is present | string | uri format. |
| Optional | object | Email delivery settings. | |
| email.recipients | Required when email is present | array<string> | 1 <= items <= 10; each item is an email string. |
Exact source contract; all request body fields are optional at the top level.
| Field | Required | Type | Constraints / notes |
|---|---|---|---|
| success | Required | boolean | Top-level response field. |
| notification | Required | object | Updated notification subscription. |
| notification.id | Required | string | Notification subscription ID. |
| notification.channel | Required | string | "webhook" | "email". |
| notification.profileId | Required | string | null | Profile scope, or null. |
| notification.eventTypes | Required | array<string> | Event values from the documented enum. |
| notification.onlyScheduledPosts | Required | boolean | Scheduled-posts-only filter. |
| notification.enabled | Required | boolean | Enabled state. |
| notification.webhook | Optional | object | Present for webhook channel. |
| notification.webhook.url | Required when webhook is present | string | uri format. |
| notification.webhook.secret | Required when webhook is present | string | Webhook signing secret. |
| notification.email | Optional | object | Present for email channel. |
| notification.email.recipients | Required when email is present | array<string> | 1 <= items <= 10; each item is an email string. |
| notification.lastTestAt | Required | string | null | date-time or null. |
| notification.lastTestStatus | Required | string | null | Last test status, or null. |
| notification.createdAt | Required | string | date-time. |
| notification.updatedAt | Required | string | date-time. |
Exact source contract for the 200 notification object.
| Status | Response shape | What to check |
|---|---|---|
| 200 application/json | success (boolean, required) and notification (object, required) | Confirm the returned notification fields match the intended update. |
| 400 application/json | success (boolean, required) and message (string, required) | Re-check field types, eventTypes enum values, recipients count, and webhook url format. |
| 404 application/json | success (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.
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]"]
}
}'{
"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 |
|---|---|---|---|---|---|---|
| id#1 | id | string | __0 | Yes | Notification subscription ID | |
| body#2 | body | object | __0 | Yes | ||
| body#2 | body.profileId | string | null | __1 | No | ||
| body#2 | body.profileId[variant1] | string | __1_type:string | |||
| body#2 | body.profileId[variant2] | null | __1_type:null | |||
| body#2 | body.eventTypes | array<string> | __2 | No | kind: ; value: 1 <= items | |
| body#2 | body.eventTypes[] | string | __3 | kind: ; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected" | ||
| body#2 | body.onlyScheduledPosts | boolean | __4 | No | When true, deliver matching notifications only for posts that were scheduled. | |
| body#2 | body.enabled | boolean | __5 | No | ||
| body#2 | body.webhook | object | __6 | No | ||
| body#2 | body.webhook.url | string | __7 | Yes | HTTPS endpoint that receives the service JSON payloads | kind: ; value: uri |
| body#2 | body.email | object | __8 | No | ||
| body#2 | body.email.recipients | array<string> | __9 | Yes | kind: ; value: 1 <= items <= 10 | |
| body#2 | body.email.recipients[] | string | __10 | kind: ; value: email | ||
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.notification | object | __2 | Yes | ||
| response#3 | response.notification.id | string | __3 | Yes | ||
| response#3 | response.notification.channel | string | __4 | Yes | kind: schemaValueIn; value: "webhook" | "email" | |
| response#3 | response.notification.profileId | string | null | __5 | Yes | ||
| response#3 | response.notification.profileId[variant1] | string | __5_type:string | |||
| response#3 | response.notification.profileId[variant2] | null | __5_type:null | |||
| response#3 | response.notification.eventTypes | array<string> | __6 | Yes | ||
| response#3 | response.notification.eventTypes[] | string | __7 | kind: schemaValueIn; value: "post.scheduled" | "post.published" | "post.partial" | "post.failed" | "account.reauthorization_required" | "account.disconnected" | ||
| response#3 | response.notification.onlyScheduledPosts | boolean | __8 | Yes | ||
| response#3 | response.notification.enabled | boolean | __9 | Yes | ||
| response#3 | response.notification.webhook | object | __10 | No | ||
| response#3 | response.notification.webhook.url | string | __11 | Yes | kind: ; value: uri | |
| response#3 | response.notification.webhook.secret | string | __12 | Yes | Webhook signing secret (masked in list responses) | |
| response#3 | response.notification.email | object | __13 | No | ||
| response#3 | response.notification.email.recipients | array<string> | __14 | Yes | kind: ; value: 1 <= items <= 10 | |
| response#3 | response.notification.email.recipients[] | string | __15 | kind: ; value: email | ||
| response#3 | response.notification.lastTestAt | string | null | __16 | Yes | kind: ; value: date-time | |
| response#3 | response.notification.lastTestAt[variant1] | string | __16_type:string | kind: ; value: date-time | ||
| response#3 | response.notification.lastTestAt[variant2] | null | __16_type:null | kind: ; value: date-time | ||
| response#3 | response.notification.lastTestStatus | string | null | __17 | Yes | ||
| response#3 | response.notification.lastTestStatus[variant1] | string | __17_type:string | |||
| response#3 | response.notification.lastTestStatus[variant2] | null | __17_type:null | |||
| response#3 | response.notification.createdAt | string | __18 | Yes | kind: ; value: date-time | |
| response#3 | response.notification.updatedAt | string | __19 | Yes | kind: ; value: date-time | |
| response#4 | response | object | __0 | |||
| response#4 | response.success | boolean | __1 | Yes | ||
| response#4 | response.message | string | __2 | Yes |