Setup webhooks¶

This guide provides a step-by-step approach to setting up webhooks in WSO2 Identity Platform to integrate external systems.

Prerequisites¶

Ensure that you have:

Access to the WSO2 Identity Platform console.
Ability to implement a web service or endpoint accessible to WSO2 Identity Platform.

Create the external service¶

Your external web service should do the following to receive event notifications:

Expose an endpoint that accepts both HTTP GET and POST requests with JSON payloads. WSO2 Identity Platform sends GET requests for subscription and unsubscription verification. Your endpoint must respond to these GET requests with the hub.challenge string to confirm its readiness to receive events.

WSO2 Identity Platform sends POST requests to deliver the actual event notifications. These requests contain the event payload in JSON format.
Deploy this endpoint on a server accessible to WSO2 Identity Platform.

Configure a webhook in WSO2 Identity Platform¶

Follow the steps below to configure a webhook.

On the WSO2 Identity Platform Console, go to Webhooks.
Click Add Webhook and provide the following:
- Name: A descriptive name for the webhook.
- Endpoint: The URL of your web service, where WSO2 Identity Platform will send event notifications.
- Secret: A unique string for HMAC signature (x-hub-signature) header to verify event security.
- Events to subscribe: Select event types for notifications (for example choosing Logins notifies of successful and failed login attempts).
Click Create to create the webhook.
Webhooks are inactive by default. Toggle the switch to activate it during or after creation.
WSO2 Identity Platform sends a verification call upon activation. Your endpoint must respond successfully for activation to complete. Refer to Verify your webhook endpoint subscription for detailed instructions.
After creation, you can:
- Deactivate or reactivate the webhook.
- Resend subscription or unsubscription requests.
- Delete the webhook (only when inactive).

Verify your webhook subscription¶

When you activate a webhook, WSO2 Identity Platform checks if your endpoint can get notifications. It sends a separate HTTP GET verification request for each event type you subscribe to. For example, if you subscribe to Logins and Registrations, your endpoint will get two separate verification calls, one for each.

Example subscription verification request:

GET 

/hub.mode=subscribe&hub.topic=myorg.dcbd6baa-40c7-4eb9-9c2e-19b868d0e266.schema.wso2.v1.event.login&hub.challenge=500c4833-91c6-4556-b9a9-1b8e5e00d48b&hub.lease_seconds=864000

In this request:

hub.mode=subscribe indicates that WSO2 Identity Platform is verifying a subscription.
hub.topic shows the URL of the topic you subscribe to.

WSO2 Identity Platform creates the topic in the following format:

{your-root-organization-domain}.{root-or-sub-organization-id}.schema.{subscribed-event-profile-name}.{subscribed-event-profile-version}.event.{subscribed-event-type-name}
hub.challenge is a unique, random string generated by WSO2 Identity Platform. Your endpoint must return this exact string in its response body.
hub.lease_seconds specifies how long the subscription will remain active.

Upon receiving this request, your endpoint must respond with a 2xx HTTP status code and include the exact hub.challenge value in the response body.

Example response:

HTTP/1.1 200 OK
Content-Type: text/plain

500c4833-91c6-4556-b9a9-1b8e5e00d48b

This process adheres to the WebSub specification, which defines how hubs verify subscription intent.

Receive webhook events¶

WSO2 Identity Platform sends an HTTP POST request to your webhook endpoint when a subscribed event is triggered. This request contains a JSON message with event details. Your service can then use this information as needed.

Event payload structure¶

Webhook event payloads adhere to the Security Event Token (SET) specification (RFC 8417). This ensures a standardized and secure format for event information. Each payload includes:

iss (Issuer): Identifies the WSO2 Identity Platform instance that issued the event.
iat (Issued At): Timestamp showing when WSO2 Identity Platform issues the event.
rci (Request Correlation ID): A unique identifier that correlates the event with the original request that triggered it.
jti (JWT ID): A unique identifier for the event.
events: This object holds the actual event data. Its internal structure changes depending on the specific event types you've subscribed to. For instance, subscribing to Logins will deliver both successful and failed login events, with distinct data structures for each.

Example event payload for login success event:

POST /your-webhook-endpoint
Content-Type: application/json
x-hub-signature: sha256=abcdef12345... (HMAC signature)

{
  "iss": "https://api.asgardeo.io/t/myorg",
  "jti": "051f0c37-b689-44d4-b7d2-29b980ece273",
  "iat": 1751705149662,
  "rci": "05268edb-9a87-4656-87c0-0fb674dd03b1",
  "events": {
    "https://schemas.identity.wso2.org/events/login/event-type/loginSuccess": {
      "user": {
        "id": "d4002616-f00c-49d5-b9b7-63b063819049",
        "claims": [
          {
            "uri": "http://wso2.org/claims/username",
            "value": "[email protected]"
          }
        ],
        "organization": {
          "id": "6f8d17ae-1ad5-441b-b9e0-c7731e739e94",
          "name": "myorg",
          "orgHandle": "myorg",
          "depth": 0
        },
        "ref": "https://api.asgardeo.io/t/myorg/scim2/Users/d4002616-f00c-49d5-b9b7-63b063819049"
      },
      "tenant": {
        "id": "12402",
        "name": "myorg"
      },
      "organization": {
        "id": "6f8d17ae-1ad5-441b-b9e0-c7731e739e94",
        "name": "myorg",
        "orgHandle": "myorg",
        "depth": 0
      },
      "userStore": {
        "id": "UFJJTUFSWQ==",
        "name": "PRIMARY"
      },
      "application": {
        "id": "40d982e5-23be-4ee1-8540-9cb696d8c321",
        "name": "MyApp"
      },
      "authenticationMethods": [
        "BasicAuthenticator"
      ]
    }
  }
}

Event signature using hash-based message authentication code¶

To ensure the authenticity and integrity of events, WSO2 Identity Platform includes an x-hub-signature header with each webhook payload. This header contains an hash-based message authentication code (HMAC) signature computed using the Secret you provided when configuring the webhook.

Verifying the signature:

Verify the signature to confirm that WSO2 Identity Platform sent the event and that no one tampered with the payload.

Retrieve the secret: Use the same secret string you configured in WSO2 Identity Platform for the webhook.
Compute HMAC: Generate an HMAC-SHA256 hash of the raw request body using your secret as the key.
Compare Signatures: Compare the computed HMAC with the value in the x-hub-signature header. If they match, the event is authentic.

Test your webhook¶

After you configure and activate your webhook, test it by triggering the specific flow for the event type you subscribed to. This step confirms that your webhook endpoint correctly receives notifications in real-world scenarios.

Here's how to test different event types:

Login events: Initiate a login request with a user from your organization (for example through a configured application).
Registration events: Attempt to onboard a new user into your organization.
Token events: Issue or revoke an access token for a user or an application.
Session events: Create, extend, or terminate a user session within the system.
Credential events: Update the password of an existing user.
User account management events: Perform actions such as updating a user's profile or changing their account status (for example enabling or disabling a user).

Observe the requests received by your webhook endpoint to confirm that it successfully receives and processes the event notifications as expected.

Troubleshoot issues¶

If your webhook isn't functioning as expected, consider the following common issues and their solutions:

Webhook verification failed
- Problem: Your webhook is active, but you observe a subscription request error next to certain event types.
- Cause: Your endpoint may not have successfully received or responded to the subscription verification requests for the selected event types.
- Solution:
  - Ensure your endpoint URL is publicly accessible and can receive HTTP GET requests from WSO2 Identity Platform.
  - Resend the subscription request from the WSO2 Identity Platform Console (within the webhook's details page) and verify if your endpoint received these requests.
  - Check your endpoint's server logs for any errors during the verification request process. Confirm that your endpoint responds with a 2xx HTTP status code and returns the exact hub.challenge string in the response body.
Event not delivered
- Problem: Your webhook is active, but your endpoint isn't receiving event notifications when the subscribed events occur in WSO2 Identity Platform.
- Cause: Issues with network connectivity, endpoint availability, payload processing, or an unsuccessful subscription.
- Solution:
  - Verify that your webhook endpoint is online, running, and publicly accessible to WSO2 Identity Platform. Tools like curl or online HTTP testing services can help check external reachability.
  - Check your endpoint's server logs for incoming GET requests from WSO2 Identity Platform. Configure your endpoint to read the hub.challenge query parameter and respond with a 2xx HTTP status code, returning the exact hub.challenge string in the response body. WSO2 Identity Platform delivers events only after a successful subscription.
  - Ensure that no firewalls, security groups, or network ACLs are blocking incoming connections from WSO2 Identity Platform's IP ranges.
  - If your endpoint receives the request but doesn't process it, there might be an issue with your code parsing the JSON payload or handling the x-hub-signature header. Review your application logs for errors.
  - WSO2 Identity Platform retries failed deliveries. Consistent failures show a persistent issue with your endpoint. Look at addressing them.
Event signature (HMAC) mismatch
- Problem: Your endpoint receives events, but the x-hub-signature verification fails.
- Cause: You may use an incorrect secret key for HMAC computation, or you may calculate the HMAC incorrectly in your endpoint.
- Solution:
  - Make sure that the Secret configured in WSO2 Identity Platform for your webhook exactly matches the secret key used in your endpoint's signature verification logic.
  - Ensure you are computing the HMAC on the raw, unmodified request body received by your endpoint, not a parsed or formatted version. Encoding issues (for example UTF-8) can also cause mismatches.
  - Confirm you are using HMAC-SHA256, as specified by WSO2 Identity Platform.
Webhook unsubscription failed
- Problem: Your webhook is inactive, but you observe an unsubscription request error next to certain event types.
- Cause: Your endpoint may not have successfully received or responded to the unsubscription verification requests for the selected event types.
- Solution:
  - Ensure your endpoint URL is publicly accessible and can receive HTTP GET requests from WSO2 Identity Platform.
  - Resend the unsubscription request from the WSO2 Identity Platform Console (within the webhook's details page) and verify if your endpoint received these requests.
  - Check your endpoint's server logs for any errors during the verification request process. Confirm that your endpoint responds with a 2xx HTTP status code and returns the exact hub.challenge string in the response body.
Webhook receives events even if it's inactive or deleted
- Problem: Your webhook is inactive or deleted, but your endpoint still receives event notifications for the subscribed event types.
- Cause: Your endpoint may not have successfully received or responded to the unsubscription verification requests for the selected event types.
- Solution:
  - Ensure your endpoint URL is publicly accessible and can receive HTTP GET requests from WSO2 Identity Platform.
  - If your webhook is in inactive mode, resend the unsubscription request from the WSO2 Identity Platform Console (within the webhook's details page) and verify if your endpoint received these requests.
  - Check your endpoint's server logs for any errors during the unsubscription verification request process. Confirm that your endpoint responds with a 2xx HTTP status code and returns the exact hub.challenge string in the response body.
  - If you delete your webhook, contact WSO2 Identity Platform support for assistance. You can get help from the community help, send a request email to [email protected], or contact WSO2 Identity Platform support through the WSO2 cloud support portal.

Security best practices¶

To maintain the security and integrity of your webhook integration, follow these best practices:

Secure endpoint address:

Always use HTTPS for your webhook endpoint address. HTTPS encrypts event data in transit and protects it from eavesdropping. WSO2 Identity Platform lets you configure an HTTP endpoint for local testing only. Use HTTPS for all production environments.
Protect your secret:

The webhook secret verifies event authenticity. Never expose it publicly (for example, in client-side code or public repositories). Store it securely in environment variables or a dedicated secrets management service.
Verify signatures:

Always validate the x-hub-signature header for every incoming webhook event. This step protects you from spoofed or tampered events. Discard any events with invalid signatures.
Idempotency:

Design your webhook endpoint to be idempotent. Processing the same event multiple times (due to retries) should have the same effect as processing it once. This approach prevents unintended side effects.

Implementing webhooks for forward compatibility¶

When developing your webhook endpoint, it's important to design it to be robust and adaptable to future changes in WSO2 Identity Platform's event structure. WSO2 Identity Platform may introduce new event types, new event URIs, or additional properties to existing events.

Follow these guidelines to ensure your webhook implementation remains resilient and compatible with future enhancements:

Validate event URI of the exact event you want to consume
Always validate the specific event URI within the events object of the payload. For instance, if the event of interest is a login successful event, always explicitly check for https://schemas.identity.wso2.org/events/login/event-type/loginSuccess to process a successful login. This practice allows your endpoint to gracefully ignore new, unrecognized event URIs if WSO2 Identity Platform adds them to the event type in the future.
Anticipate new event indicators
WSO2 Identity Platform may trigger new events for the same event type, but associate them with different flows or resources.
- Flow indicators (initiatorType, action):
Pay attention to properties like initiatorType and action in the payload. These properties act as flow indicators. If your processing logic depends on the flow rather than just the high-level event type, ensure it handles new combinations or values for these properties. This approach lets your logic adapt when WSO2 Identity Platform triggers events for new flows.
- Resource indicators (credentialType):
Events might also apply to different resources under the same event type. For example, credential updated events currently happen for password updates, indicated by the credentialType property in the payload. In the future, the same event could happen for passkeys, TOTP, or other credential types, introducing new values for credentialType. Design your logic to safely ignore or specifically handle new values for such properties if you only want particular resource updates (for example, only password updates).
Ensure graceful unknown property handling
Avoid strict schema validation that would cause your webhook to fail if WSO2 Identity Platform adds new, optional properties to an existing event payload. Your parser should be able to ignore unrecognized properties, ensuring forward compatibility.

By following these practices, your webhook will be more adaptable to future enhancements in WSO2 Identity Platform's event delivery, requiring fewer updates on your side to maintain functionality.