Create a Webhooks Subscription

Endpoint URL: {identityDomain} /{customerId} /webhooks/subscriptions


Creates a new webhooks subscription associated with the specified customer. Webhook subscriptions determine the event types that trigger near real-time notifications: when one of these events occurs, a webhooks notification is sent to a listener endpoint created and maintained by the organization associated with the subscription.

Note that the Webhooks v3 APIs all have an API response timeout of 10 seconds.

Respects the API Client Allow List: No

Base URL

The base URL for this endpoint is your Identity Cloud API URL, including the appropriate region. For example, if you are in the US region, then your base URL will look like this:

If you are in the Australian (AU) region your base URL will look like this: 


This endpoint requires token-based authentication. To obtain an access token, you must use a confidential client (using the client ID as the username and the client secret as the password) to access the /{customerId}/login/token endpoint. The access token returned from that endpoint is then used in the Authorization header of your API call. For example, if you get back the access token 03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle then your Authorization header will look like this when using Curl:

-H 'Authorization: Bearer 03v-eeodppPrrHXXIx56pRLyDBaOldDxqEwI59MFCFGVuSkLRapzgmfwmEHyKWle'

In Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field.

URL path parameters








Unique identifier of the organization (customer) associated with the new webhooks subscription. For example:


Request Parameters

Request parameters must be formatted using JSON (JavaScript Object Notation) and included in your API call’s body parameter. Valid request parameters include the following:








Boolean value indicating whether the webhooks subscription is enabled or disabled. When a subscription is disabled, webhooks will not attempt to deliver any events for that subscription. 

For example:

"enabled": false

The default value is true.




URL of the webhooks listener endpoint. For example:

"endpoint": ""

See the article Configuring Listener Endpoints for information about the allowed (and disallowed) URL types.


string array


Array of Identity Cloud events that the webhooks subscription responds to. For example:

"events": ["entityCreated", "entityDeleted", "entityUpdated"]



“Friendly” name given to the webhooks subscription. The title must contain at least 2, but no more than 200, characters. For example:

"title": "Akamai Documentation Webhooks Subscription"

Note that titles must be unique across a specific customer. For example, Customer A can only have one subscription with the title Webhooks Subscription; any attempt to create a second subscription with this same title will fail. However, Customers B, C, D, and E can also have one subscription with the title Webhooks Subscription.

NoEnables you to add a filter to (or remove a filter from) a Webhooks subscription. Filters provide a way for you to restrict the number of events forwarded to your listener endpoint; for example, instead of receiving notifications for all your entityCreated events, you can receive notifications only for entityCreated events associated with a specific application or a specific entity type. See Creating a Webhooks Filter for more information. 

Sample Request (curl)

The following command creates a new webhooks subscription (Akamai Documentation Webhook Subscription) associated with customer ID 9bc867ed-1f10-420f-8d90-398fde4e4779. This new subscription will be enabled immediately after creation, and subscribes to three event types: entityCreated; entityDeleted; and entityUpdated.

curl -X POST \ \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' \
  -H 'Content-Type: application/json' \
  -d '{
       "enabled": true,
       "events": ["entityCreated", "entityDeleted", "entityUpdated"],
       "title": "Akamai Documentation Webhooks Subscription"


201 Created

If your call to this endpoint succeeds, you'll get back detailed information about the new webhooks subscription:

  "subscriptionId": "639f771b-cbbc-4d92-8f3b-e5a1ed041a63",
  "customerId": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2020-01-28T18:11:27.064269Z",
  "updatedAt": "2020-01-28T18:11:27.064269Z",
  "title": "Akamai Documentation Webhooks Subscription",
  "endpoint": "https;//",
  "events": [
  "enabled": true,
  "_links": {
    "self": {
      "href": "/00000000-0000-0000-0000-000000000000/webhooks/subscriptions/639f771b-cbbc-4d92-8f3b-e5a1ed041a63"

Error Response Codes

The following table includes information about some of the other response codes that you might encounter when calling this endpoint.

Response Code



Bad Request. This typically means that your API request did not pass the JSON schema validation. Verify that you are using correctly-formatted JSON in the request parameter and then try again.


Forbidden. You do not have permission to access the requested resource. You will often see this error if you are using an expired access token. By default, access tokens can only be used for one hour before they need to be replaced.


Not found. The specified customer could not be found.