Get Notification API: Get a Notification Subscription
The Get Notification API retrieves a single notification subscription by ID. Use it to inspect the subscription channel, subscribed eventTypes, scheduled-post scope, enabled state, webhook or email configuration, and last test outcome before deciding whether to update or test the subscription.
Get a notification subscription — GET {{API_BASE_URL}}/v1/notifications/{id}
The Get Notification API retrieves one notification subscription. Send a GET request to {{API_BASE_URL}}/v1/notifications/{id}, replacing {id} with the notification subscription ID. The operation has no request body in the supplied contract. Use the returned notification object to confirm the channel, eventTypes, onlyScheduledPosts setting, enabled state, and associated profileId before making changes elsewhere.
Authorization — x-access-key header
Authorization uses the x-access-key header. Send the token as the header value in the x-access-key header on the GET request. The supplied contract names the header and its location but does not describe token acquisition, rotation, or provisioning, so do not assume additional authorization fields.
Path Parameters — id
The path contains one required parameter. The id parameter is a required string and represents the notification subscription ID. Replace the placeholder in the path with that ID exactly as stored; the contract does not define additional path parameters, query parameters, or a request body for this operation.
Response Body — notification field map
A successful response returns success and a notification object. Read channel to determine whether the subscription uses the webhook or email channel. Read eventTypes for the subscribed events, onlyScheduledPosts for the scheduled-post scope, and enabled for the current enabled state. The profileId field is required but nullable, so a null value is a valid returned value rather than a missing field.
Webhook and email configuration
For a webhook subscription, inspect webhook.url and webhook.secret when those fields are present. For an email subscription, inspect email.recipients, which contains between 1 and 10 email-formatted strings. The webhook and email objects are optional in the notification object, so check channel together with the presence of each object instead of assuming both are always returned.
Test status and timestamps
Use lastTestAt and lastTestStatus to see when the subscription was last tested and what outcome was recorded. Both fields are required but nullable, so null means no value is present for that field in the returned object. Use createdAt and updatedAt, both required date-time strings, to understand when the subscription was created and last updated.
Error Responses — 400 and 404
The 400 and 404 responses both use application/json with success and message fields. The supplied contract does not define specific error codes, message values, or the exact conditions that trigger each status, so treat the status and shape as the contract and do not infer additional error fields. Refer to the failure matrix for the exact distinction between the 200, 400, and 404 shapes.
Worked Example — origin-modular request and annotated 200 response
Use the worked example titled Get Notification API request example with a placeholder subscription ID and placeholder token. Then compare the response with the worked example titled Get Notification API 200 response example. Check that success is true, that notification.id matches the requested ID, and that channel, eventTypes, onlyScheduledPosts, enabled, profileId, lastTestAt, lastTestStatus, createdAt, and updatedAt are interpreted according to the field map.
| Field | Type | Required | Constraints or notes |
|---|---|---|---|
| success | boolean | required | Top-level response field. |
| notification | object | required | Top-level response field containing the subscription. |
| notification.id | string | required | Notification subscription ID. |
| notification.channel | string | required | Enum: webhook | email. |
| notification.profileId | string | null | required | Nullable profile identifier. |
| notification.eventTypes | array<string> | required | Enum values: post.scheduled | post.published | post.partial | post.failed | account.reauthorization_required | account.disconnected. |
| notification.onlyScheduledPosts | boolean | required | Controls scheduled-post scope. |
| notification.enabled | boolean | required | Current enabled state. |
| notification.webhook | object | optional | Present for webhook configuration when returned. |
| notification.webhook.url | string | required when webhook is present | Format: uri. |
| notification.webhook.secret | string | required when webhook is present | Webhook signing secret; described as masked in list responses. |
| notification.email | object | optional | Present for email configuration when returned. |
| notification.email.recipients | array<string> | required when email is present | 1 to 10 items; each item format: email. |
| notification.lastTestAt | string | null | required | Nullable; format: date-time. |
| notification.lastTestStatus | string | null | required | Nullable last test outcome. |
| notification.createdAt | string | required | Format: date-time. |
| notification.updatedAt | string | required | Format: date-time. |
Exact response contract for the 200 notification object; webhook and email are optional objects, while profileId, lastTestAt, and lastTestStatus are required but nullable.
| Status | Content type | Response shape | Contract notes |
|---|---|---|---|
| 200 | application/json | success: boolean; notification: object | Returns the notification subscription object described in the field map. |
| 400 | application/json | success: boolean; message: string | Error response shape; triggering condition not supplied. |
| 404 | application/json | success: boolean; message: string | Error response shape; triggering condition not supplied. |
Exact status and shape mapping from the supplied contract; no error codes or message values were supplied.
| Input | Location | Type | Required | Notes |
|---|---|---|---|---|
| id | path | string | required | Notification subscription ID in /v1/notifications/{id}. |
| x-access-key | header | string | required | Authorization token header. |
Exact request inputs from the supplied contract; no query parameters or request body were supplied.
Frequently asked questions
What inputs does the Get Notification API require?
Send GET to {{API_BASE_URL}}/v1/notifications/{id} with the required string path parameter id set to the notification subscription ID and an x-access-key header containing the token.
How do the 200, 400, and 404 responses differ?
A 200 response returns success and a notification object. The 400 and 404 responses use the success and message shape shown in the failure matrix, without additional fields in the supplied contract.
Which fields should I check first when interpreting a retrieved notification subscription?
Check channel, eventTypes, onlyScheduledPosts, enabled, profileId, and lastTestStatus. For webhook subscriptions inspect webhook.url and webhook.secret; for email subscriptions inspect email.recipients, which contains 1 to 10 email-formatted strings.
curl -X GET "{{API_BASE_URL}}/v1/notifications/<notification-subscription-id>" -H "x-access-key: <token>"{
"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 | |
| 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: schemaFormat; 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: schemaItems; value: 1 <= items <= 10 | |
| response#2 | response.notification.email.recipients[] | string | __15 | kind: schemaFormat; value: email | ||
| response#2 | response.notification.lastTestAt | string | null | __16 | Yes | kind: schemaFormat; value: date-time | |
| response#2 | response.notification.lastTestAt[variant1] | string | __16_type:string | kind: schemaFormat; value: date-time | ||
| response#2 | response.notification.lastTestAt[variant2] | null | __16_type:null | kind: schemaFormat; 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 |