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 CategoryEvent TypeDefinitionMethod
CONSENTCONSENT_REVOKEDYou will be informed when an end-user revokes consent at a provider's website or portal.Webhook
CONSENTCONSENT_UPDATEDYou 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
MAINTENANCEPLANNED_OUTAGEThere is a planned outage by a Provider or Akoya that is going to occur.Webhook
MAINTENANCESERVICEThere 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

TermDefinition
SubscriptionContains the information for the subscription such as category, method, effective date, and other metadata.
Effective DateAny metadata about communicating with that subscriber (e.g. auth, retry policy)
TypeA type of message (e.g. Account Consent, Outage)
CategoryA group of related message types (e.g. Maintenance - which contains Service, Planned Outage, etc.)
CallbackA destination that can receive a notification, usually a URL or email
Effective DateDate at which a subscriber would like to begin receiving notifications for a given subscription
NotificationAn event that contains a category, type, payload (title+message), etc.
ProviderPlace 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!