📘

The content on this page deals with Webhooks 2.0. Webhooks is still a supported feature of the ​Akamai​ Identity Cloud; however, new customers interested in this technology might want to take a look at the article Introduction to Webhooks v3, a completely overhauled, more powerful, and largely self-service update to Webhooks 2.0.

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

1. Request a webhook through the Support Portal.

2. Provide required configuration information (listed above).

3. ​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.