/{customerId}/webhooks/ subscriptions/{subscriptionId}

Enables you to view modify, or delete a webhooks subscription.

This endpoint supports the following methods:

  • GET
  • PATCH
  • DELETE

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:

https://v1.api.us.janrain.com

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

https://v1.api.au.janrain.com 

Authentication

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.


GET

Description

Returns information about the specified webhooks subscription. 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.

URL path parameters

Parameter

Type

Required

Description

{customerId}

UUID

Yes

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

9bc867ed-1f10-420f-8d90-398fde4e4779

{subscriptionId}

UUID

Yes

Unique identifier of the webhooks subscription being returned. For example:

454fe969-1909-4e93-b552-674d47eafdb0

Request Parameters

No additional parameters are required to call this endpoint.

Sample Request (curl)

The following command returns information about the webhooks subscription with the subscription ID 454fe969-1909-4e93-b552-674d47eafdb0:

curl -X GET \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/webhooks/subscriptions/454fe969-1909-4e93-b552-674d47eafdb0 \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' 

Responses

200 OK

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

{
    "subscriptionId": "454fe969-1909-4e93-b552-674d47eafdb0",
    "customerId": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2020-01-27T16:53:36.309183Z",
    "updatedAt": "2020-01-27T16:53:36.309183Z",
    "title": "Gregs test subscription",
    "endpoint": "https://webhook.site/46ff3c5e-ae95-43df-b32d-d07bb84746b4",
    "events": [
        "entityCreated",
        "entityUpdated",
        "entityDeleted"
    ],
    "enabled": true,
    "_links": {
        "self": {
            "href": "/00000000-0000-0000-0000-000000000000/webhooks/subscriptions/454fe969-1909-4e93-b552-674d47eafdb0"
        }
    }
}
 

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

Description

403

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.

404

Not found. The specified customer and/or the specific webhooks subscription could not be found.






PATCH

Description

Modifies a webhooks subscription. Webhook subscriptions specify 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.

URL path parameters

Parameter

Type

Required

Description

{customerId}

UUID

Yes

Unique identifier of the organization (customer) whose webhooks subscription is being modified. For example:

9bc867ed-1f10-420f-8d90-398fde4e4779

{subscriptionId}

UUID

Yes

Unique identifier of the webhooks subscription being modified. For example:

454fe969-1909-4e93-b552-674d47eafdb0

Request Parameters

Request parameters must be formatted as JSON objects and included in your API call’s body parameter. Valid request parameters include the following:

Parameter

Type

Required

Description

enabled

boolean

No

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.

endpoint

URL

Yes

URL of the webhooks listener endpoint. For example:

"endpoint": "https://listener.documentation.akamai.com"

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

events

string array 

Yes

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

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

title

string

Yes

“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 all have a subscription with the title Webhooks Subscription.

Headers

The following header must be included in your API call:

Parameter

Required

Parameter Value

Content-Type

Yes

application/merge-patch+json


Sample Request (curl)

The following command modifies the webhooks subscription with the ID 454fe969-1909-4e93-b552-674d47eafdb0:

curl -X PATCH \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/webhooks/subscriptions/454fe969-1909-4e93-b552-674d47eafdb0 \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' 
  -H 'Content-Type: application/merge-patch+json' \
  -d '{
       "enabled": true,
       "endpoint":"https;//webhooks.documentation.akamai.com",
       "events": ["entityCreated", "entityDeleted", "entityUpdated","entityPurged"],
       "title": "Akamai Documentation Webhooks Subscription"
}'

Responses

200 OK

If your call to this endpoint succeeds, you'll get back updated property values for the subscription:


    "subscriptionId": "454fe969-1909-4e93-b552-674d47eafdb0",
    "customerId": "00000000-0000-0000-0000-000000000000"
    "createdAt": "2020-01-27T16:53:36.309183Z",    "updatedAt": "2020-01-28T19:36:47.514908Z",
    "title": " Akamai Documentation Webhooks Subscription ",
    "endpoint":" https;//webhooks.documentation.akamai.com",
    "events": [
        "entityCreated",
        "entityDeleted"
    ],
    "enabled": true,
    "_links": {
        "self": {
            "href": "/00000000-0000-0000-0000-000000000000/webhooks/subscriptions/454fe969-1909-4e93-b552-674d47eafdb0"
        }    }
}


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

Description

400

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.

403

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.

404

Not found. The specified customer and/or the specific webhooks subscription could not be found.






DELETE

Description

Deletes the specified webhook subscription. After a subscription has been deleted organizations no longer receive notifications for the event types associated with the subscription. In addition, any events still in the event store that are associated with the subscription are deleted.

URL path parameters

Parameter

Type

Required

Description

{customerId}

UUID

Yes

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

9bc867ed-1f10-420f-8d90-398fde4e4779

{subscriptionId}

UUID

Yes

Unique identifier of the webhooks subscription being deleted. For example:

454fe969-1909-4e93-b552-674d47eafdb0

Request Parameters

No request parameters are required in order to call this endpoint.

Sample Request (curl)

The following command deletes the webhook subscription with the ID 454fe969-1909-4e93-b552-674d47eafdb0:

curl -X DELETE \
  https://v1.api.us.janrain.com/9bc867ed-1f10-420f-8d90-398fde4e4779/webhooks/subscriptions/454fe969-1909-4e93-b552-674d47eafdb0 \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' \
  -H 'Content-Type: application/json' 

Responses

204 No Content

If your call to this endpoint succeeds, you won’t get back a full API response. Instead, you'll get back a 204 No Content status code.

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

Description

403

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.

404

Not found. The specified customer and/or the specific webhooks subscription could not be found.