Webhooks

Webhooks allow you to subscribe to certain events from either our Partner Portal or your dedicated instance. When one of the configured events is triggered by our system, an HTTP POST request will be initiated to the configured webhook URL with information about the event that was triggered as well as specific event parameters. The HTTP request payload will contain a JSON object.

Webhooks can be configured in your Partner Portal account.

Authorization

Clym webhook requests are signed using the webhook secret (available in your account) and is placed under the X-Clym-Signature HTTP header. The signature itself is composed of two parts: timestamp and hmac_sha256(timestamp) and has the following format:

X-Clym-Signature: {unixTimestamp}.{hmac.sha256(unixTimestamp, webhookSecret)}

A simple way of verifying the authenticity of the request is by extracting the timestamp from the signature, re-creating the HMAC hash using your webhook secret and compare the two values. An example can be found below:

const crypto = require('crypto');
function verifySignature(header, secret) {
 try {
   const timestamp = header.slice(0, 13);     // unix millisecond timestamp 
   const ts = new Date(parseInt(timestamp));
   if (isNaN(ts)) return false;
   // Verify time drift, do not allow requests older than 30 seconds.
   if ((Date.now() - ts) > 30000) return false;     
   const headerSignature = header.slice(14);
   const verifySignature = crypto.createHmac('sha256', secret)
          .update(timestamp)
          .digest('hex');
   return verifySignature === headerSignature;
 } catch (e) {
   return false;
 }
}

Each webhook has its own secret that can (and should) be rotated regularly.

Payload structure

The payload of a webhook is a JSON object that contains the following properties:

• event - the event code that occurred

• params - an object with the event parameters

• entity - the entity information that was changed/affected.

  • kind - the kind of entity that was affected (eg: account, domain, partnerMerchant, etc.)

  • data - object containing the full (or partial) representation of the affected entity

The following example shows the HTTP headers and payload of a merchant.created event:

X-Clym-Signature: 1753103241469.00d67a9c70aa1b575fdec79d6b9d86be70695f583c6a19ff67f5e16225ee8a59
User-Agent: clym.io-webhook
Content-Type: application/json

{
   "event": "merchant.created"
   "params": {
     "id": "65baac66a33746e99a73d74c4rdsifb7",
     "merchant_id": "my-merchant-id"
   },
   "entity": {
     "type": "partnerMerchant",
     "data": {
       "id": "65baac66a33746e99a73d74c4rdsifb7",
       "merchant_id": "my-merchant-id",
       "created_at": "2025-05-02T11:00:00.000Z"
     }
   }
}

Delivery

Clym tries to deliver the webhook shortly after the event was triggered. In the event that your server is unable to properly return a 200 OK status code for a webhook request, our system will retry the delivery up to 5 times with a 3-minute delay between requests. You can also manually retry webhook triggers from your Clym Partner Portal account.