Setup a Webhook Cronjob

SyncPulse allows you to set up cronjobs that send webhooks to any external URL. This is useful for integrating with third-party services, triggering external APIs, or notifying other systems about events in your SyncPulse project.

Setup instructions

To set up a cronjob that sends a webhook to an external URL, follow these steps:

1. Open your project dashboard: Go to your SyncPulse console and select your project.

2. Navigate to the Cronjobs section: On the sidebar, click on Cronjobs under the Resources section.

3. Create a new Cronjob: Click the Create cron button and enter the following:

   • Name: Give your cronjob a descriptive name.
   • Type: Choose Webhook.
     • URL: Enter the target URL to be triggered, its should starts with https! http is not supported for security reasons.
     • Method: Choose the HTTP method, supported methods are GET, POST, PUT, DELETE and PATCH.
     • Body (Optional): Enter the body of the request in JSON or Text format
     • Headers (Optional): Add any custom headers you want to include in the request.
     • Parameters (Optional): Add any query parameters you want to include in the request url.
     • Send HMAC signature in header (Optional): If enabled, SyncPulse will send a HMAC signature in the header of the request. This can be used to verify the authenticity of the request on the receiving end.
   • Schedule: Enter the cron expression or use the UI to set the schedule.

Request limits

SyncPulse imposes certain limits on the size and number of requests to ensure optimal performance and security. Here are the key limits to keep in mind when setting up your webhook cronjob:

SyncPulse Headers

Once syncpulse sends the request, it will add some headers to the request. Here are the headers that SyncPulse adds to the request:

This headers could not be modified or removed, and they are automatically added to the request by SyncPulse. You can use these headers to identify the source of the request and verify its authenticity.

Verify the webhook (Optional)

If you enabled the HMAC signature option, you can verify the webhook request on the receiving end, this will protect your webhook from unauthorized access such as replay attacks. To verify the webhook request, you need to following datas:

• Project Client Secret: This is the secret key that you can find in your SyncPulse project settings. You can use this key to generate/verify the HMAC signature.

Header key x-syncpulse-hmac-sha256 contain the HMAC signature of the request timestamp, you can use this signature to verify the authenticity of the request.

Example of verifying the HMAC signature

Here is an example of how to verify the HMAC signature in your webhook endpoint using Node.js:

async function createHmac(message, secret) {
  const enc = new TextEncoder();
  const key = await crypto.subtle.importKey(
    "raw",
    enc.encode(secret),
    { name: "HMAC", hash: "SHA-256" },
    false,
    ["sign"]
  );
  const signature = await crypto.subtle.sign("HMAC", key, enc.encode(message));
  return Array.from(new Uint8Array(signature))
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}
 
function timingSafeEqual(a, b) {
  if (a.length !== b.length) return false;
  let result = 0;
  for (let i = 0; i < a.length; i++) {
    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }
  return result === 0;
}
 
export async function verifyHmac(message, signature, secret) {
  const expectedSig = await createHmac(message, secret);
  return timingSafeEqual(expectedSig, signature);
}

Verify the HMAC signature in your endpoint:

import { verifyHmac } from "./hmac.js";
 
// your existing code...
 
const signature = req.headers["x-syncpulse-hmac-sha256"];
const timestamp = req.headers["x-syncpulse-timestamp"];
 
const verify = await verifyHmac(timestamp, signature, process.env.SYNCPULSE_CLIENT_SECRET);
 
if (!verify)  {
  // Syncpulse did not send this request
  return res.status(401).json({ error: "Invalid signature" });
}

This will ensure that the request is coming from SyncPulse and has not been tampered with, as is mentioned, this is optional, but it is highly recommended to use it for security reasons.