Configure webhook subscriptions

Ultimately, Webhooks v3 comes down to subscriptions: without at least one webhook subscription you won’t ever receive an event delivery. To get webhook events delivered to you, you need to create a subscription or two. (Or even more, as the case may be.)

Subscriptions tell the Identity Cloud what events to look for and where to send any relevant events it happens to find. For example, suppose you create a webhooks subscription that looks for the entityCreated event (or, more correctly, an entityCreated event associated with your customer ID). If such an event is found the subscription packages the event information into a security event token and then forwards that token to the webhooks receiver (e.g., https://webhooks.documentation.akamai.com). 

That’s a very simple example of a webhooks subscription, and a Curl command for creating such a subscription looks similar to this:

curl -X POST \
  https://v1.api.us.janrain.com/9bc867ed-1f10-420f-8d90-398fde4e4779/webhooks/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{
     "enabled": true,
     "endpoint":"https://webhooks.documentation.akamai.com",
     "events": ["entityCreated"],
     "title": "Akamai Documentation Webhooks Subscription"
}
'

As you can see, this command specifies:

• The webhooks delivery endpoint (https://webhooks.documentation.akamai.com).

• The event that triggers the webhooks notification (entityCreated).

• The current status of the subscription (enabled, meaning that events are processed and delivered).

• A user-friendly title assigned to the subscription (Akamai Documentation Webhooks Subscription). Titles, by the way, must be unique across a given customer. Customer A can only have one subscription titled Akamai Documentation Webhooks Subscription; any attempt to create a second subscription with the same title will fail. However, nothing prevents Customers B. C, and D from each having a subscription titled Akamai Documentation Webhooks Subscription.

After you have your subscription, and after the subscription is enabled, you’ll get webhook notifications any time a new entity is created. (Assuming, of course, that the entity was created in one of your entity types, as determined by your Akamai ID.)

And that’s great. But what if you wanted something a little more complicated; for example, what if you wanted to be notified when any of three different events (entityCreated, entityUpdated, entityDeleted) took place? What then?

If you want to be notified about multiple events, you have two options: 1) create multiple event subscriptions, one for each event type; or, 2) create a single subscription that watches for more than one event type. For example, here’s a Curl command that creates a subscription that watches for all three entity events (entityCreated, entityUpdated, entityDeleted):

curl -X POST \
  https://v1.api.us.janrain.com/9bc867ed-1f10-420f-8d90-398fde4e4779/webhooks/subscriptions \
  -H 'Content-Type: application/json' \
  -d '{
     "enabled": true,
     "endpoint":"https://webhooks.documentation.akamai.com",
     "events": ["entityCreated", "entityUpdated", "entityDeleted"],
     "title": "Akamai Documentation Webhooks Subscription"
}
'