❗️
On September 30, 2023 the Akamai Identity Cloud will decommission both Webhooks v2 and the Export Service. After September 30 these two legacy services will no longer be available. Instead, organizations will need to upgrade to the newer versions of these services:

Webhooks v3

Integration Bus: Data Export

These new versions are both self-configurable. However, you will need to engage with your Identity Cloud representative to provide visibility into, and to turn off, your legacy services.
Akamai recognizes that this decommission announcement may result in unplanned effort and inconvenience on your end. However, the Akamai team is committed to working with you to help make this transition as seamless as possible. Please contact your Identity Cloud representative for more information.

Webhooks are used to keep track of the state of user data within Registration. Webhooks may be created to send notifications whenever a user record is created, changed, or deleted. Once configured, Akamai delivers changes in state to a predetermined URL as a JSON object. If an error occurs, Akamai will try to send the message three times to avoid temporary networking glitches.

Note that, for security reasons, Webhooks only supports HTTPS endpoints (that is, endpoints protected by TLS 1.0 and later).

Required configuration information

The following information is needed to configure a webhook:

Capture Application ID
Entity Type. What Capture entity type should each webhook respond to (typically user).
Callback URL (or URLs). What URL to POST to for each webhook. Supported protocols:
- HTTPS (TLS 1.0 and above)
Event Types.– What sort of events should each webhook respond to:
- ADD. When a user record is created.
- UPDATE. When profile information from a user record is updated.
  - For the UPDATE event type, you must provide a list of user record profile attribute changes each webhook should respond to. A list of attributes to choose from can be found in the Console in the View a schema article.
- DELETE. When a user record is deleted.
Callback Hash (optional) – A unique identifier for each webhook. If a callback hash is not provided, Akamai will generate one for you.

Implementation steps

Request a webhook through the Support Portal.
Provide required configuration information (listed above).
Akamai will contact you when the webhook is deployed and ready to use.

Retry system

The retry system handles network problems and other transient issues. In the event that a webhook call fails, the system will retry the call up to three times; retries occur if a webhook fails to respond within 10 seconds. This 10-second retry interval is not configurable.

When a failure happens, the event is logged with Akamai.

Webhook payloads

Webhook payloads are included in the body of POST requests as JSON objects inside an array. Each payload consists of:

The uuid of the user record
The entity_type used
A timestamp recording when the event took place
The callback hash
The client_id from where the webhook was triggered

To verify that a webhook payload originated with Akamai , compare the callback hash value in the payload with the callback hash established when the webhook was configured.

When an action triggers the webhook, Akamai sends a JSON object to the callback URL defined in the configuration. You will need to implement code to process the information delivered to this location.

The following is an example payload from a webhook:

[
  {
    "uuid":"12345678-4321-1234-4321-123456789123",
    "entity_type":"user",
    "datetime":"2012-04-07T22:26:10.947Z",
    "hash": "1234567891234567891234567891234567891234",
    "client_id":"98765432198765432198765432198765"
  }
]

Responding to webhooks

As a best practice, upon receiving the webhook call the endpoint should add the payload to a queue for further processing, then respond with an HTTP status code of 200 as quickly as possible. The response body is ignored by Webhooks. Using a queue to process the incoming payload enables the callback endpoint to respond quickly without blocking additional requests from Webhooks.