Webhook

Build & set up the webhook to subscribe events from Suger service


Overview

Webhooks allow you to build or set up integrations by subscribing to certain events on Suger platform. When one event is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update the entitlement status & metering/billing of your clients to your production server.

Create Webhook

Creating a webhook is a two-step process. You'll first need to set up how you want your webhook to behave through Suger: what events should it listen to. After that, you'll set up your server to receive and manage the payload.

To set up a webhook, go to the settings page of your organization. From there, click button CREATE WEBHOOK. Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.

  • Each organization is only allowed to have single Webhook. If your organization already has one and would like to create a new one, the old one has to be deleted first.

Payload URL

The payload URL is the URL of the server that will receive the webhook POST requests.

Secret

Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are from Suger. When you set a secret, you'll receive the X-Suger-Signature-256 headers in the webhook POST request. For more information on how to use a secret with a signature header to secure your webhook payloads, see Secure Your Webhook.

Content Type

The webhook request is sent using the default content type as application/json, which delivers the JSON payload directly as the body of the POST request.

Edit Webhook

You can edit the webhook by changing the Payload URL, Secret or both.

Test Webhook

The webhook can be tested by clicking the button TEST. A test event is sent as POST request from Suger to the payload URL. The schema of event payload is defined here. You can verify whether your webhook endpoint could receive the request and validate the signature (more details see Secure Your Webhook).

Payload of webhook test event
{     "organizationID": "your-suger-organization-id",     "action": "TEST",     "entityType": "ORGANIZATION",     "entityID": "your-suger-organization-id"}

Secure Your Webhook

Ensure your server is only receiving the expected Suger requests for security reasons. Once your server is configured to receive payloads, it'll listen for any payload sent to the endpoint you configured. For security reasons, you probably want to limit requests to those coming from Suger.

When your secret token is set, Suger uses it to create a hash signature (HMAC SHA 256) with each payload. This hash signature is included with the headers of each request as X-Suger-Signature-256. You can validate it by computing the signature in your server like this:

Ruby
def verify_signature(payload_body, webhook_secret, signature_from_request)  signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), webhook_secret, payload_body)  return halt 500, "Signatures didn't match!" unless Rack::Utils.secure_compare(signature, signature_from_request)end
Golang
func verify_signature(payload_body []byte, webhook_secret string, signature_from_request string) bool {  h := hmac.New(sha256.New, []byte(webhook_secret))  h.Write(payload_body)  signature := "sha256=" + hex.EncodeToString(h.Sum(nil))  return signature == signature_from_request}
  • Your language and server implementations may differ from this example code. However, no matter which implementation you use, the hash signature starts with "sha256=", using the key of your secret token and your payload body.

Webhook Event Payload

After the webhook is created & configured, the triggered event is sent as POST request to the Payload URL. Each webhook event payload also contains properties unique to the event. You can find the unique properties in the individual event type sections.

KeyTypeDescription
organizationIDstringThe ID of Suger organization
actionstringThe action performed. Can be one of:
  • CREATE: the entity is created.
  • CANCEL: the entity is cancelled.
  • SUSPEND: the entity is suspended, it may be reinstated or cancelled in the future.
  • REINSTATE: the entity is reinstated from suspended state.
  • UPDATE: the entity is updated.
  • TEST: for testing purpose only. More details.
entityTypestringThe type of the entity who are under the action. Can be one of:
  • ORGANIZATION
  • PRODUCT
  • OFFER
  • ENTITLEMENT
entityIDstringThe ID of the entity

Webhook Retry & Expire

  1. Suger service sends each webhook event only once if succeed (receive HTTP status 200). Otherwise it will retry to send events every 6 hours for up to 7 days. The events who have not been sent successfully for 7 days will expire.
  2. For the same entity, if the previous event is not sent successfully, but the new one has come, then the previous one expires immediately. Your webhook endpoint only receive the latest event for each entity.