List Your Webhook Subscriptions

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


Description

Returns information about the webhook subscriptions associated with the specified customer. Webhooks 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.


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.


URL path parameters

Parameter

Type

Required

Description

{customerId}

UUID

Yes

Unique identifier of the organization (customer) whose webhooks subscriptions are being returned. For example:

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


Query Parameters

The following query parameter can also be used with this endpoint:

Parameter

Type

Required

Description

page

integer


No

If you have a large number of subscriptions, you can return subscription information in batches (referred to as pages). The page parameter provides a way to specify the results page to be returned. For example, setting page to 3 returns only the subscriptions found on page 3 of the results.

If you set this value to a page that doesn’t exist (for example, you set page to 10 even though you only have 6 pages of subscriptions) the last page is returned.


Sample Request (curl)

The following command returns information about all the webhooks subscriptions associated with customer ID 9bc867ed-1f10-420f-8d90-398fde4e4779:

curl -X GET \
  https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/webhooks/subscriptions \
  -H 'Authorization: Bearer Xk7EzdpGq5GPQcsxCWM2SxdlwU_iTsA4i2Px4TEzBrfLIvddjnDVBJxjPDuCARHH' 


Responses

200 OK

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

{
  "total": 2,
  "_links": {
    "self": {
        "href": "/00000000-0000-0000-0000-000000000000/webhooks/subscriptions/"
      }
    },
  "_embedded": [{
    "subscriptionId": "fafd23cf-ec8d-49a0-a640-7cfc144e2aec",
    "customerId": "00000000-0000-0000-0000-000000000000",
    "createdAt": "2020-01-17T18:54:05.328449Z",
    "updatedAt": "2020-01-27T16:27:10.441876Z",
    "title": "Paulo test subscription",
    "endpoint": "https://16ea3669.ngrok.io/path/to/endpoint",
    "events": [
      "entityCreated",
      "entityUpdated",
      "entityDeleted"
      ],
    "enabled": true,
    "_links": {
      "self": {
        "href": "/00000000-0000-0000-0000-000000000000/webhooks/subscriptions//fafd23cf-ec8d-49a0-a640-7cfc144e2aec"
        }
      }
    },
  {
    "subscriptionId": "e5269842-024f-49bf-8a39-67aec8048b42",
    "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//e5269842-024f-49bf-8a39-67aec8048b42"
        }
      }
    }
  ]
}


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 could not be found.