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 recieve proactive service, maintenance, and consent alerts.
Notifications extend value to your end-users
Maintenance notifications
Ensure your end-users never experience a failed API call. Proactively re-route traffic when informed of upcoming provider outages.
Consent notifications
Quickly reach out and engage with end-users that either revoke or renew consent with marketing communications.
Coming soon!
Akoya will be requiring MTLS authentication for your callbackURL. This will enhance security for your end-users.
Retrieve a service token
In order to subscribe to notifications, you will need a service token. 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 | You will be informed when an end-user revokes consent at a provider's website or portal. | Webhook |
| CONSENT | CONSENT_UPDATED | You will be informed when an end-user 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 above. -
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 our Event Notifications API.
Example subscription object:
{
"notificationSubscriptions": [
{
"category": "MAINTENANCE",
"type": "PLANNED_OUTAGE",
"callbackUrl":"https://example.com/notification",
"callbackEmail": "[email protected]",
"effectiveDate": "2021-11-24"
}
]
}
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
Note
You would have to have an existing subscription in order to test this. The available test events are the same as the ones listed above.
Handle the event
Typically, you would use webhooks to receive events. Please 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, please log 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.
Note
You will need to use the service token for this call.
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, please use the PATCH for 'Update Notifications' and update your preferences there!