Enabling, Disabling, and Deleting Webhook Subscriptions

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/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/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.)

Important. It's useful to know that you don't have to worry about disabling an entityCreated subscription if you call the the entity.bulkData endpoint. Although that endpoint is designed to create  thousands of accounts in a single operations, the endpoint does not generate webhook events: if you use the entity.bulkData endpoint to create 10,000 user accounts you won't get any webhook notifications. That's because entity.bulkData doesn't generate entityCreated events; as a result, there's nothing for Webhooks v3 to report. This is also true if you use the dataload data migration script: because the dataload script relies on the entity.bulkCreate endpoint that means that no webhook events are generated during a data migration.

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 disadvantages 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.

Note. 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.  

Here’s a blow-by-blow comparison that illustrates the difference between disabling a webhooks subscription and deleting a webhooks subscription:

Subscription StatusEvents Already in Event StoreNew EventsEvent Deliveries
DisabledAll events currently in the event store remain in the event store. However, each event is marked as failure and no attempt is made to deliver any of those events.
 
Events which occur while the subscription is disabled are added to the event store, but are marked as failure. These events remain marked as failure even when the subscription is re-enabled.
 
No deliveries take place while a subscription is disabled; deliveries will resume as soon as the subscription is re-enabled. 
DeletedAll events currently in the event store are deleted. These events cannot be restored.Events are no longer monitored. No new events are added to the event store.Events are no longer delivered to the customer (at least not for the deleted subscription).