Setup webhooks
Preview
¶

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

Note

This feature is currently in Preview. Functionality and event payloads may change during development.
Expect updates without prior notice.

Prerequisites¶

Ensure that you have:

Access to the Asgardeo console.
Ability to implement a web service or endpoint accessible to Asgardeo.

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. Asgardeo 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.

Asgardeo 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 Asgardeo.

Configure a webhook in Asgardeo¶

Follow the steps below to configure a webhook.

On the Asgardeo 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 Asgardeo 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.
Asgardeo 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, Asgardeo 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 Asgardeo is verifying a subscription.
hub.topic shows the URL of the topic you subscribe to.

Asgardeo 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 Asgardeo. 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¶

Asgardeo 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 Asgardeo instance that issued the event.
iat (Issued At): Timestamp showing when Asgardeo 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, Asgardeo 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 Asgardeo sent the event and that no one tampered with the payload.

Retrieve the secret: Use the same secret string you configured in Asgardeo 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 Asgardeo.
  - Resend the subscription request from the Asgardeo 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 Asgardeo.
- 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 Asgardeo. Tools like curl or online HTTP testing services can help check external reachability.
  - Check your endpoint's server logs for incoming GET requests from Asgardeo. 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. Asgardeo delivers events only after a successful subscription.
  - Ensure that no firewalls, security groups, or network ACLs are blocking incoming connections from Asgardeo'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.
  - Asgardeo 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 Asgardeo 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 Asgardeo.
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 Asgardeo.
  - Resend the unsubscription request from the Asgardeo 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 Asgardeo.
  - If your webhook is in inactive mode, resend the unsubscription request from the Asgardeo 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 Asgardeo support for assistance. You can get help from the community help, send a request email to [email protected], or contact Asgardeo 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. Asgardeo 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 Asgardeo's event structure. Asgardeo 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 Asgardeo adds them to the event type in the future.
Anticipate new event indicators
Asgardeo 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 Asgardeo 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 Asgardeo 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 Asgardeo's event delivery, requiring fewer updates on your side to maintain functionality.

Setup webhooks Preview¶