Webhooks

Webhooks can be sent in multiple forms, including HTTP requests and Slack-compatible messages. This document describes HTTP webhook usage.

Introduction

Webhooks are sent as HTTP POST requests containing JSON formatted data. The purpose is to let the receiver know that an event of certain type occurred, and they might react to this in some way. A webhook call is performed in response to specific actions, such as the creation or modification of an user account.

The Trigger

A webhook request is sent in response to a change in the system. For example, the creation or modification of an user account.

User event	Type code
User account was created	USER_CREATE
User account was modified	USER_EDIT
User account was deleted	USER_DELETE
User's last activity time changed	USER_ACTIVITY_UPDATED
User's email address was verified	USER_EMAIL_VERIFIED
User's LegalInfo data was updated	USER_LEGALINFO_CHANGE
User's mobile number was verified	USER_MOBILE_VERIFIED
User's address data was modified	USER_ADDRESS_CHANGE
User's consent data was updated	USER_CONSENT_UPDATED
User's PNS tokens were updated	USER_PNS_TOKEN_CHANGE

Group event	Type code
Group was created	GROUP_CREATE
Group was modified	GROUP_EDIT
Group was deleted	GROUP_DELETE

See the Webhook editor in the Management UI for the full list of webhook event types.

Webhook Request

The webhook request content includes basic data of the triggering event. It has enough information to identify the type of event, and the target of the event. This is enough for the recipient to determine if the event is interesting. In such case, the recipient may retrieve more information through the Management API.

The webhook call typically contains just the identifiers of the event target, which enables the receiver to retrieve more data if necessary. The data is serialized as JSON content.

Typical webhook fields:

Field	Purpose
id	Target of event, for example user ID when modifying an user account
type	Type of event
time	Timestamp of event
webhookId	Identifier for webhook configuration
webhookCallId	Identifier for this request (do retries have the same id?)
data	Free form data, content depends on type of event

Example JSON webhook request content

{
  "id": "65645e360a3c9d1354097ef6",
  "type": "USER_EDIT",
  "time": "2024-09-03T12:55:14.178Z",
  "webhookId": "66d7069f5d58f830d11f322a",
  "webhookCallId": "66d707325d58f830d11f323f",
  "namespaceCode": "root",
  "data": {
    "changedProperties": [
      "emails",
      "emails/0.address",
      "lastChangedEmail"
    ]
  }
}

Response to received webhook call

The integrated HTTP service should respond to the webhook call with response status code 200 to indicate it received it correctly. Any error response status code means the ID service will retry sending the webhook call later for a number of times.