Monitor user profile activity with Webhooks 2.0
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
-
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.
Updated 15 days ago