Getting started

Webhooks allow you to automate and integrate workflows by triggering events when specific actions occur. This section provides detailed guidance on various webhook-related actions, including creating and testing webhooks, validating webhook deliveries, and editing or disabling webhooks.

Creating webhooks

In SCALAR, webhooks are created and maintained using the Subscription Module
A webhook endpoint must have a URL and a list of events. The webhook can be created as follows:

• Get the webhook URL: Obtain the webhook URL from the destination application where the data will be received. This URL is the endpoint to which the source application will send data.

  📘

  Note

  Ensure that ports 80 and 443 are publicly accessible.

• Configure the Webhook: In the SCALAR Subscription Module, create a new Subscription and configure the subscription to send data to the webhook URL.
• We can configure the webhook using the Datahub Portal Module in SCALAR by clicking Subscriptions and then selecting Add Subscription.

Handle the payload

• HTTP request: When the specified event occurs, the source application sends an HTTP request (a POST request) to the webhook URL.
• Receive data: Upon triggering, the destination application receives an HTTP request containing data related to the event.
• Payload format: The payload has a specified format in JSON.

Each event published will be in a specific schema, this schema will have following details:
"eventBatchId": "020db07f-6e95-470e-8cc0-a371f9deed2b" This property (GUID) identifies each unique Batch of data sent to the customer uniquely.

"eventSubscriptionId": "517db07f-6e95-475e-8cc0-a371f9deed2b" This identifies the Subscription (in DHS) for which the data was sent.

"eventBatchTime": "1970-01-20T06:39:05.683Z" This identifies the Date and Time when the batch was sent.
"eventsData": This contains the payload of the Batch and is constructed using EventsData from the Incoming Event.

{
	"eventBatchId": "020db07f-6e95-470e-8cc0-a371f9deed2b",
	"eventSubscriptionId": "517db07f-6e95-475e-8cc0-a371f9deed2b",
   	 "eventBatchTime": "1970-01-20T06:39:05.683Z",    	
    	"eventsData": [ // this will have the full batch of all messages
    { 
      	"eventType": "address.created",
	 "eventVersion": 1,
      	"eventData": { // this will have the actual message 
          	"registeredOn":"1970-01-20T06:39:05.683Z"  
      }
    }
    	]
}

• Your webhook script or server processes this payload and performs any necessary actions based on the received data.
  • Return a 2XX Status Code Quickly.
  • SCALAR expects your application to return a 2XX status code upon the successful receipt of the notification.
  • It's best to return a 2XX code as soon as you have verified the contents. Do longer-running processing asynchronously.
  • In case of long processing times, the system may have a timeout and retry sending the message.

Validating webhook deliveries

The webhook URLs are mostly publicly open. Hence, there is always a security concern of someone accessing URL and posting improper data. Hence, implementing security measures is crucial. The following are the most important measures:

• Add security measures to your webhook by using a secret key.
• Generate a random string (the secret key) and include it in the subscription configuration. The source application uses this secret key to sign the payload.
• The destination application can then verify the signature to ensure that the data came from a trusted source.

1. The server / API provider will compute the signature of the plain message that will be sent. The signature is a hash-based message authentication code (HMAC) of a shared secret + the plain message.
2. The plain message and the signature will be sent as a packet to the client.
3. Upon receiving the packet, the client / application will compute the signature using the plain message received.
4. The signature computed by the client is compared to the signature sent by the server. This is to verify the authenticity of the message/request.

Editing webhooks

Administrators can edit or update the webhooks according to the requirement. This includes editing the URL, modifying the list of enabled events, or changing the status of your subscription.
More information: Edit subscription