Link

Webhooks

Accesstype has the ability to inform third party system by webhook calls that it makes to any third party systems.


How to Setup Accesstype webhooks

  1. Login to Accesstype and go to Settings > Outgoing webhooks > Add Webhook
  2. Enter the URL that you would like Accesstype to make a POST call to.
  3. Optionally enter a Secret in case you wish to verify and segregate the calls made from Accesstype. Click here for more info on how to verify Accesstype webhooks.
  4. Check the Active checkbox. This is useful to activate the webhook when Accesstype automatically disables in case of failures.
  5. Select one or more events for which for which you would want the webhook call to be made, and press save.

How Accesstype Outgoing Webhooks work

  • Once the webhooks are set up, Accesstype makes a POST API call to the webhook URLs specified, as and when the event(s) occur. The payload is like below
    {
      "event": "subscription.created", // name of the event
      "event_timestamp": "2019-06-16T14:04:39.836Z", // UTC time at which event occurred
      "data": {
        "subscription": { // object representing the resource on which the vent occurred, 
          ...
        } 
      }
    }
    
  • The Webhook request body contains the Event Name and the Subscription Object.
  • When the third party system receives the request, it is advised to return back a success response (200, 201, 2xx).
  • In case the external system responds will a failure (non 2xx), then Accesstype will send an email to the Admins and Owners of the Accesstype account along with the payload and will also retry making the webhook call every hour. Accesstype will discontinue retrying the webhook call when it receives a success response or after 24 retries, whichever is earlier.
  • If the failures continue to persist, Accesstype will disable the webhook.
  • The disabled webhook can then be re-activated in the dashboard by going to Accesstype.com > Settings > Outgoing Webhooks > Activate. Note: Accesstype server waits for 10 seconds to open a connection with the destination server and 5 seconds to receive a response form it.

Description of events

Event name Applicability Description
subscription.expiry One-time and Recurring Subscriptions Triggered when a one-time-subscription has expired or a recurring subscription which was cancelled, has come to an end.
subscription.cancellation One-time and Recurring Subscriptions Triggered when a one-time or a recurring subscription is cancelled.
subscription.renewal Recurring Subscriptions Triggered when a recurring subscription is successfully renewed for the subsequent cycle.
subscription.creation One-time and Recurring Subscriptions Triggered when a new subscription is created.
subscription.entered_grace_period Recurring Subscriptions Triggered when the payment is pending for a recurring subscription, and is not yet renewed. Note: When a payment is due for a recurring subscription, Accesstype waits for the payment for a grace period of 5 days before it marks the subscription as expired. During this grace period, the subscriber continues to gain access to the content.
subscription.activated One-time and Recurring subscriptions Triggered when a subscription which was created in the Pending state, becomes Active.
subscription.expiry_reminder One-time Subscriptions Triggered as per the Number of Days Before Subscription Expiry in the webhooks dashboard
subscriber.creation -NA- Triggered when a new Subscriber is created in Accesstype.
invoice.creation One-time and Recurring subscriptions Triggered when an invoice is created for a payment
subscriptionattempt.initiated One-time and Recurring subscriptions Triggered when users initiates a Subscription Attempt
subscriptionattempt.failed One-time and Recurring subscriptions Triggered when Subscription attempt fails due to payment and validation errors

Verify Webhooks sent by Accesstype

signature = request.headers['X-AT-Signature']
digest = OpenSSL::Digest.new('sha256')
secret = "foobar" # the secret that you have set in dashboard of Accesstype
message = request.body.read
digest = OpenSSL::HMAC.hexdigest(digest, secret, message)
ActiveSupport::SecurityUtils.secure_compare(digest, signature)

This section is useful when the Outgoing Webhooks feature is enabled in Accesstype dashboard under Accesstype > Settings > Outgoing Webhooks and if the field Secret has a value setup in the webhook.

Each webhook request will include a base64-encoded X-AT-Signature in the header, which is generated using the Secret that is setup in the Accesstype dashboard.

To verify that the request came from Accesstype, the HMAC digest must be computed according to an algorithm and compared with the value in the X-AT-Signature header. If they match, then you can be sure that the webhook was sent from Accesstype.

An example of the algorithm for signature verification is seen here in Rails.


Table of contents