Webhook events
Webhooks are a way for different online services or applications to communicate with each other in near-real time. They allow an application to send data to another application when a specific event occurs. This mechanism is commonly used to automate processes and keep different systems in sync without the need for constant manual intervention.
Webhook registration and deregistration are key concepts in the setup and management of webhooks. These processes involve enabling and disabling the communication channel between two applications through webhooks.
Webhook overview
Configuring a webhook flow consists of several general steps:
-
Set up the webhook. The receiving app (the webhook consumer) sets up a webhook with an endpoint URL. The endpoint URL listens for incoming webhook payloads from the sending app (the webhook provider).
As an Okta admin, you might set up a webhook to receive notifications when events happen in the Okta platform. This event could be, for example, a new user creation, an authentication event, or a password reset.
Alternatively, you might configure your webhook with a third-party app to notify you of external changes so you can update details within your Okta org.
-
Register the webhook. Establishing a webhook requires you to register an endpoint URL with the provider. This location is where your receiving app listens for incoming data.
-
Configure the endpoint URL. The receiving app (the webhook consumer) provides an endpoint URL. This is the URL that listens for incoming webhook payloads from the sending app (webhook provider).
-
Subscribe to events. The webhook provider, which could be an external app or a service like Okta, permits you to subscribe to specific events. For example, user creation or deactivation, a sign in attempt, or other types of events relevant to the provider's functionality.
-
Configure the payload. During webhook registration, you can configure the payload format and content. This includes specifying what data the webhook provider needs to include in the payload when an event occurs.
-
Confirm or verify the endpoint URL. Some webhook systems require a verification step to ensure that the provided endpoint URL is valid and under your control. This may involve the webhook provider sending a verification token to your endpoint that requires a response to complete validation.
-
Activate the webhook: After successful registration, the active webhook is ready to receive event notifications. When specified events occur, the provider sends payloads containing relevant data to your registered endpoint URL.
-
-
Set an event trigger. When a specific event occurs on the provider platform, the provider generates a payload containing relevant information about the event.
-
Receive the payload. The webhook provider then sends an HTTP POST request containing the payload with event details to the URL that you registered. The data is typically sent in JSON format.
-
Process the payload. The receiving app's server processes the incoming POST request. It parses the JSON payload and performs actions based on the event data. This could involve updating a database, sending notifications, or triggering some other business logic.
When handling webhook payloads, there are two processing aspects to consider:
-
Request aggregation. Incoming payloads can be received as individual items, or as a collected batch of items.
-
Batched request processing. For payloads arriving as a collected batch, the webhook event flow can process each item individually or handle the entire batch as one item.
-
-
Respond to the provider. After the receiving app has processed the payload, it sends an HTTP response back to the provider. This response indicates whether the receiver successfully received and processed the payload.
-
Set up a retry mechanism. Sometimes, due to network issues or other reasons, the webhook delivery might fail. To ensure reliability, many webhook systems implement a retry mechanism. If the initial delivery attempt fails, the system makes extra attempts to deliver the payload.
-
Deregister the webhook if you no longer need to receive certain event notifications, if you're switching to a different endpoint, or decommissioning the webhook.
-
Remove the endpoint URL. To deregister a webhook, you typically inform the webhook provider to stop sending payloads to a specific endpoint URL.
-
Unsubscribe from events. Similar to registration, you might need to specify which events you want to unsubscribe from. This ensures that you no longer receive event notifications for those events.
-
Deactivate the webhook. After you successfully deregister from the events at the provider, you deactivate the webhook for your endpoint URL so you no longer receive event payloads.
-
Webhooks involve exchanging data over the internet, so security is crucial. Implementing proper authentication and authorization mechanisms, such as API keys or tokens, helps ensure that only authorized parties can send or receive webhook data.