One of the cool things about Webhooks v3 is this: it’s remarkably easy to enable and disable a given webhooks subscription (in fact, you can even delete a webhooks subscription if you don’t need that subscription anymore). Don’t want to receive webhook notifications for awhile? Then disable your subscriptions. Want to start receiving webhook notifications again? Then re-enable your subscriptions. It’s that simple.

For example, here’s an API call that disables webhook subscription 454fe969-1909-4e93-b552-674d47eafdb0:

curl -X PATCH \
  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/merge-patch+json' \
  -d '{
       "enabled": false
      }'

And here’s an API call the re-enables that subscription:

curl -X PATCH \
  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/merge-patch+json' \
  -d '{
       "enabled": true
      }'

Just set the enable property to false to disable a subscription, and set the enabled property to true to enable a subscription.

Like we said: easy. But, the again, ease-of-use might not be the issue here. Instead, the issue might be this: why would you even want to disable/re-enable a webhooks subscription in the first place?

The obvious answer, of course, is, “Because you don’t want to receive webhook notifications for awhile.” But why wouldn’t you want to receive notifications for awhile? Well, suppose your webhook endpoint needs to be taken offline in order to do a software upgrade. If your endpoint is offline it can’t receive notifications; so why bother having those notifications sent? Instead, disable the subscription, then re-enable the subscription when the endpoint is back online. (And don’t worry: no data will be lost while the subscription is disabled.)

Another scenario in which disabling webhooks might be called for is this: if you are doing a data migration. Suppose you previously employed a different Customer Identity and Access Management service and are now switching to the Akamai Identity Cloud. As part of that switch, you need to migrate 1 million user accounts from the old service to the Identity Cloud. You probably don’t want to receive 1 million “new account created” webhook notifications: that has the potential to completely overwhelm you network and your webhooks endpoint.

📘

Actually, Akamai would probably cut off access to your system long before you could send 1 million webhook notifications. In that case, you wouldn’t get all the notifications, but you also wouldn’t get all your data migrated, either.

The moral of the story? If you’re going to do a data migration, you should:

1. Disable your webhook subscriptions (or at least any subscriptions that apply to the creation of new user accounts).

2. Complete your data migration.

3. Re-enable your webhook subscriptions.

Admittedly, it’s easy to say, “Just disable your webhook subscription.” But what are the ramifications of disabling a webhooks subscription? If you disable a subscription, what happens to all the events that take place while the subscription is out of service? As we noted, there are some advantages to disabling a subscription: reduced network traffic and less strain on your webhooks endpoint. But are there any _dis_advantages to disabling a webhooks subscription?

Let’s see if we can address some of these questions. When a webhooks subscription is disabled, any deliveries currently in progress will be completed: Webhooks v3 will not abandon a delivery attempt in midstream. In addition to that, future events will continue to be monitored by event consumers. However, the event state for those new events will be set to failure, and the events will not be delivered to customers; instead, they’ll go straight to the event store. 

You can think of enabling and disabling a webhooks subscription as being similar to turning a lamp on or off. The current state of the lamp is temporary: if the lamp is off, you can change the state, and turn the lamp back on simply by flipping the wall switch. Webhooks work in much the same way: make one API call to turn webhooks on, then make another API call to turn webhooks off.

Suppose, however, that you throw the lamp away. If you do that it doesn’t matter how many times you flip the wall switch: nothing is going to happen because the lamp no longer exists. This is equally true if you delete a webhooks subscription: you can’t re-enable a deleted subscription because the subscription no longer exists. If you delete a subscription, event notifications will no longer be sent to you (at least not for the deleted subscription), and any existing events will no longer be available to you. What if you change your mind and want to collect events again ? To do that, you’ll have to create a brand-new subscription. However, there won’t be a way to recover any events that occurred from the time you deleted the old subscription to the time you created the new subscription. Furthermore, all the events stored in the database prior to you deleting your subscription will be inaccessible. Disabling a webhooks subscription is reversible. Deleting a webhooks subscription is not.

📘

So if you delete a webhooks subscription you lose access to all the events associated with that subscription? Yes. Or, more technically, you lose access to all the events still in the event store. But, needless to say, you’ll still have copies of all the events that were delivered to you and have been stored in your database.

If you decide to delete a webhooks subscription you can use an API call similar to this one:

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'

Remember: when you delete a webhooks subscription, that subscription and all its events are deleted. There is no way to restore a deleted subscription or to retrieve the deleted events.  

In addition to disabled or deleted webhooks subscriptions: When a subscription has been inactive for 45 days, it will be marked as “terminated” and events will stop being collected. A terminated subscription cannot be enabled again; it must be deleted and re-created.

Subscription states

The status of a subscription is indicated by the state attribute, which you can see when you GET a webhooks subscription. The following table illustrates the difference between subscription states: