Subscriptions

webhookie provides the capability for you to implement subscriptions to your webhooks the way you need them to be. From as simple as an API call, to set up a subscription, to more secure approaches that make sure subscriptions are validated and approved – webhookie gives you the toolbox.

What are subscriptions? #

Subscriptions enable a consumer to subscribe to a topic (i.e. webhook) they have discovered.

A subscription consists of:

  • A topic the consumer wants to subscribe to.
  • The consumers application that wants the data.
  • A callback for that application which is the endpoint (and related security) where the events should be sent.

Subscription states and workflow #

webhookie provides flexibility in how you implement subscription workflows for your API consumers. As a webhook API provider you can decide:

  • who gets access to discover and request a subscrption
  • if you require a subscription to be approved before it is activated or simply allow the developer to activate the subscription directly based on the fact that they are authorized to discover the webhook API. (new with release 1.3.3)

When a user has an ACTIVATED subscription they will receive events for the subscribed topic to the callback configured within the subscription. ACTIVATED is only one of the states a subscription can be in. The full list is provided below:

  • DRAFT – The subscription has been created but not validated or activated. In this state, no events will be received by your subscription. The next step is to validate the subscription.
  • VALIDATED – The subscription has been validated by sending a sample message to the callback. If webhookie gets a 2XX response back, your subscription will be validated. This state only occurs for subscriptions which don’t require approval. In this state, no events will be received by your subscription. The next step is to activate the subscription.
  • READY TO SUBMIT – This state is equivalent to the VALDIATED state but for subscriptions that require approval. In this state, no events will be received by your subscription. The next step is to submit the subscription for approval.
  • SUBMITTED – The subscription has been submitted for approval. The subscription must now be approved or rejected by the API provider. In this state, no events will be received by your subscription.
  • APPROVED – The subscription has been approved by the API provider. The subscription can now be activated by the API consumer. In this state, no events will be received by your subscription.
  • REJECTED – The subscription has been rejected by the API provider. The API consumer must delete this subscription and try again if they wish to still subscribe. In this state, no events will be received by your subscription.
  • ACTIVATED – Activating a subscription is a simple state change that is done when you are ready to start receiving the events. A subscription must be VALIDATED (if no approval is required) or APPROVED to be activated. In this state, events will flow to the configured callback within your subscription. From this state, you can deactivate your subscription to stop receiving events.
  • DEACTIVATED – The subscription has been deactivated from an activated state. In this state, events will not flow to your subscription and they will also not be queued. From this state, you can activate the subscription to start receiving events again.
  • BLOCKED – The subscription has been blocked by webhookie as an event is getting a 5XX (server error) or 404 (not found) error consistently. In this state, events will not flow to your subscription but they will be queued. From this state, you can activate or validate your subscription. Once activated again the events will start flowing to your subscription including any queued/backed up events while it was blocked.
  • SUSPENDED – The subscription has been suspended by the Webhook API provider. In this state, the events will not flow to your subscription and they will not be queued. Only the Webhook API provider can unsuspend a suspended subscription.

Subscriptions can be deleted in all of the states above except for ACTIVATED. A subscription must be first deactivated before it can be deleted.

Creating a subscription #

Subscriptions are created by users with a WH_CONSUMER role.

A subscription is created with the following steps

  1. Click Subscribe on the webhook you want to subscribe to
  2. Create Application – this application is a logical container for the callbacks associated with it. It should reflect the name of the application that hosts the callback.
  3. Create Callback – this is the actual callback URL details. In CE you can choose to secure your callback with a HMAC signature (if you need a few more security options then please check out our Enterprise edition).
  4. Save the Subscription
  5. Test the Subscription – Webhookie will send the example request body to your callback. If you get a 2XX response from your callback then you are good to proceed. A tested subscription is known as a VALIDATED subscription.
  6. Activate the Subscription – your callback will now start receiving traffic when the events occur.

Learn more #

Read more about:

Powered by BetterDocs