Skip to content

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.

Notification object field map
FieldTypeRequiredConstraints or notes
successbooleanrequiredTop-level response field.
notificationobjectrequiredTop-level response field containing the subscription.
notification.idstringrequiredNotification subscription ID.
notification.channelstringrequiredEnum: webhook | email.
notification.profileIdstring | nullrequiredNullable profile identifier.
notification.eventTypesarray<string>requiredEnum values: post.scheduled | post.published | post.partial | post.failed | account.reauthorization_required | account.disconnected.
notification.onlyScheduledPostsbooleanrequiredControls scheduled-post scope.
notification.enabledbooleanrequiredCurrent enabled state.
notification.webhookobjectoptionalPresent for webhook configuration when returned.
notification.webhook.urlstringrequired when webhook is presentFormat: uri.
notification.webhook.secretstringrequired when webhook is presentWebhook signing secret; described as masked in list responses.
notification.emailobjectoptionalPresent for email configuration when returned.
notification.email.recipientsarray<string>required when email is present1 to 10 items; each item format: email.
notification.lastTestAtstring | nullrequiredNullable; format: date-time.
notification.lastTestStatusstring | nullrequiredNullable last test outcome.
notification.createdAtstringrequiredFormat: date-time.
notification.updatedAtstringrequiredFormat: 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.

Response and failure matrix
StatusContent typeResponse shapeContract notes
200application/jsonsuccess: boolean; notification: objectReturns the notification subscription object described in the field map.
400application/jsonsuccess: boolean; message: stringError response shape; triggering condition not supplied.
404application/jsonsuccess: boolean; message: stringError response shape; triggering condition not supplied.

Exact status and shape mapping from the supplied contract; no error codes or message values were supplied.

Request input contract
InputLocationTypeRequiredNotes
idpathstringrequiredNotification subscription ID in /v1/notifications/{id}.
x-access-keyheaderstringrequiredAuthorization 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.

Get Notification API request example
curl -X GET "{{API_BASE_URL}}/v1/notifications/<notification-subscription-id>" -H "x-access-key: <token>"
Get Notification API 200 response example
{
  "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"
  }
}
Get Notification API 400 and 404 response shape
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
id#1idstring__0YesNotification subscription ID
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: schemaFormat; 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: schemaItems; value: 1 <= items <= 10
response#2response.notification.email.recipients[]string__15kind: schemaFormat; value: email
response#2response.notification.lastTestAtstring | null__16Yeskind: schemaFormat; value: date-time
response#2response.notification.lastTestAt[variant1]string__16_type:stringkind: schemaFormat; value: date-time
response#2response.notification.lastTestAt[variant2]null__16_type:nullkind: schemaFormat; 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