Receive webhooks and check signatures

Steps

1. 1
   Step 1Mark as done: step 1

   Open Notifications

   Under Settings in the left-hand menu, click Notifications and scroll to Slack, Discord and webhook.

   Where to find it in Skylane

   1. Settings
   2. Notifications
   3. Slack, Discord and webhook
2. 2
   Step 2Mark as done: step 2

   Add your webhook URL

   Paste your address into Your own webhook URL and click Add Your own webhook.

   Skylane

   ProfileNotificationsSecurityDeveloper

   NotificationsYour own webhook URLhttps://example.com/skylane-webhookAdd Your own webhook

3. 3
   Step 3Mark as done: step 3

   Copy the signing secret

   Under Copy your webhook signing secret now, click Copy and save the secret in your server's secret settings. It is shown only once. Then click I have saved it.

4. 4
   Step 4Mark as done: step 4

   Choose the events

   Scroll up to the Alerts table. In the Your own webhook column, switch on each event you want, such as Post failed or Account needs reconnecting. These ticks save straight away.

5. 5
   Step 5Mark as done: step 5

   Check the signature on every message

   Each request carries a Skylane-Signature: t=<unix time>,v1=<hex> header. v1 is an HMAC-SHA256 of the timestamp, a full stop and the raw body, using your secret. Reject messages that do not match or are more than 5 minutes old.

   import crypto from "node:crypto";
   
   // rawBody must be the exact bytes Skylane sent. Do not parse and re-serialise the JSON first.
   export function verifySkylane(rawBody, header, secret, toleranceSeconds = 300) {
     const fields = Object.fromEntries(String(header || "").split(",").map((part) => part.split("=", 2)));
     const timestamp = Number(fields.t);
     if (!timestamp || !fields.v1) return false;
     if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
     const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex");
     const a = Buffer.from(expected, "hex");
     const b = Buffer.from(fields.v1, "hex");
     return a.length === b.length && crypto.timingSafeEqual(a, b);
   }
   
   // Express example: keep the raw body for this route.
   // app.post("/skylane-webhook", express.raw({ type: "application/json" }), (req, res) => {
   //   if (!verifySkylane(req.body, req.get("Skylane-Signature"), process.env.SKYLANE_WEBHOOK_SECRET)) return res.sendStatus(401);
   //   const event = JSON.parse(req.body);
   //   res.sendStatus(200); // reply first, then do the slow work
   // });

6. 6
   Step 6Mark as done: step 6

   Or check it in Python

   The same check in Python, matching Skylane's own reference code:

   import hashlib
   import hmac
   import time
   
   
   def verify_skylane(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
       """raw_body must be the exact bytes Skylane sent."""
       try:
           fields = dict(item.split("=", 1) for item in header.split(","))
           timestamp = int(fields["t"])
           supplied = fields["v1"]
       except (AttributeError, KeyError, ValueError):
           return False
       if abs(time.time() - timestamp) > tolerance:
           return False
       message = str(timestamp).encode() + b"." + raw_body
       expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
       return hmac.compare_digest(expected, supplied)

7. 7
   Step 7Mark as done: step 7

   Reply quickly

   Reply with any 2xx status within 10 seconds, then do slow work afterwards. The Skylane-Event header names the event so you can route it before parsing.