Build & set up the webhook to subscribe events from Suger service
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.
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 and find the Notification
section. 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.
organization
can only 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.POST
requests.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.application/json
, which delivers the JSON payload directly as the body of the POST
request.You can edit the webhook by changing the Payload URL
, Secret
or both.
The webhook can be tested by clicking the button TEST
. A test event is sent as POST
request from Suger to the payload URL. See the event payload schema for details. You can verify whether your webhook endpoint could receive the request and validate the signature
(more details see Secure Your Webhook).
{ "organizationID": "your-suger-organization-id", "action": "TEST", "entityType": "ORGANIZATION", "entityID": "your-suger-organization-id", "timestamp": "2023-02-03T03:47:09.128234Z"}
By enabling the webhook scope configuration, you can create a whitelist of products for the events to be notified via webhook. Go to the settings page and find the Notification
section. From there, click the button Edit
of Notification Configs. Now you can specify the webhook scope as shown below.
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:
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
Here is an example of signature you can use to test your code:
Wehbhook Secret new-test-webhook-secret Payload Body {“organizationID”:“gYZf-_JtH”,“action”:“TEST”,“entityType”:“ORGANIZATION”,“entityID”:“gYZf-_JtH”} X-suger-signature-256 sha256=5bc797b5f4508d4424edbe608faf1b57fe613b5d08256495e6c8cac0ef5b2584
sha256=
", using the key of your secret token and your payload body.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 sections below.
Key Type Description organizationID
string
The ID of Suger organization
action
string
The action performed. Can be one of:
CREATE
: the entity is created.CANCEL
: the entity is cancelled.PENDING_CANCEL
: the entity is pending to be 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.entityType
string
The type of the entity
who are under theaction
. Can be one of:
ORGANIZATION
PRODUCT
OFFER
ENTITLEMENT
INTEGRATION
entityID
string
The ID of the entity
entityType
= ENTITLEMENT
and action
= PENDING_CANCEL
, the entitlement will be cancelled within ONE hour. Your service is responsible to report all remaining usage records to Suger within 30 minutes once receiving this event.entityType
= ENTITLEMENT
and action
= SUSPEND
, the most common reason is the buyer's cloud billing account fails to pay the invoice in cloud marketplaces. It requires your revenue team or customer account manager to investigate the issue together with your clients.HTTP status 200
). Otherwise it will retry to send events after 10 seconds, 20 seconds, 40 seconds and then 1 minute (max retry gap duration) for 12 hours. The events who have not been sent successfully for 12 hours will expire and no retry any more.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
.