Notifications API Guide
The Akoya Notifications API enables users to retrieve notices about significant changes to the status of an item on the Akoya network.
Subscribing to event notifications allows you to receive proactive service, maintenance, and consent alerts.
Notifications Extend Value to Your Consumers
Maintenance Notifications
Ensure your consumers never experience a failed API call. Proactively re-route traffic when informed of upcoming provider outages.
Consent Notifications
Quickly reach out and engage with consumers that either revoke or renew consent with marketing communications.
Retrieve a Service Token
You need a service token to subscribe to notifications. Reference the service tokens guide for more information.
Event Category
Next, determine which categories you'll want to subscribe to.
Event Category | Event Type | Definition | Method |
|---|---|---|---|
CONSENT | CONSENT_REVOKED | The API notifies you when a consumer revokes consent at a provider's website or portal. | Webhook |
CONSENT | CONSENT_UPDATED | The API notifies you when a consumer updates consent at a provider's website or portal. This could mean that they have updated their account list and/or other account related activities. | Webhook |
MAINTENANCE | PLANNED_OUTAGE | There is a planned outage by a provider or Akoya that is going to occur. | Webhook |
MAINTENANCE | SERVICE | There is an unplanned outage by a provider or Akoya that is occurring. | Webhook |
Create a Notification Subscription
You'll need to provide the following information with each notification subscription.
category: This is the category of notification.
type: This is the type that falls under the corresponding category of notification listed in the Event Category chart.
callbackUrl: The URL to receive webhooks from Akoya. Must be HTTPS.
callbackEmail (optional field): The email to receive further details related to notification.
effectiveDate: Effective date of when the subscriber wants to receive the notification.
With the service token as a bearer token with the call, use the Create notification subscription endpoint in the Event Notifications API.
Example subscription object:
JSON
Test in Sandbox
If you’d like to validate your notifications system in sandbox, you can use the following endpoint to send a test event to your server.
https://sandbox-api.akoya.com/notifications/v1/test
See the Notifications API spec for more information.
Handle the Event
Typically, you would use webhooks to receive events. See our Webhooks guide.
As soon as you have received the event object, check the type to know what kind of event happened. You can use one webhook to handle several different event types at once, or set up individual endpoints for specific events.
Allow List
Your webhook may need to add Akoya IPs to your allow list. If you need this list, sign in to the Data Recipient Hub and file a support ticket.
Retrieve Information About the Event
You will need to use the URL sent with the previous POST payload to retrieve the details regarding that event.
Glossary
Term | Definition |
|---|---|
Subscription | Contains the information for the subscription such as category, method, effective date, and other metadata. |
Effective Date | Any metadata about communicating with that subscriber (e.g. auth, retry policy) |
Type | A type of message (e.g. Account Consent, Outage) |
Category | A group of related message types (e.g. Maintenance - which contains Service, Planned Outage, etc.) |
Callback | A destination that can receive a notification, usually a URL or email |
Effective Date | Date at which a subscriber would like to begin receiving notifications for a given subscription |
Notification | An event that contains a category, type, payload (title+message), etc. |
Provider | Place that originates the notification |
Tips
If you need to update your subscription, for example the effective date that you'd like to start consuming these notifications, use the PATCH for 'Update Notifications' and update your preferences there!