Notifications API guide (BETA)

Subscribing to event notifications allows you to receive 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.

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.

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": "example@email.com",
            "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

Please see the Notifications API spec for more information.

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 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

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!