🔔 Webhooks (Beta): Real-Time Notifications for Your Bookings

A webhook is a message that Cowlendar sends to your server the moment something happens: a booking is created, canceled, rescheduled and more. You do not have to keep asking the API.

Use webhooks together with the Public API (Beta) to build integrations with your CRM, ERP, or any custom app.

Where to find it: Shopify admin > Apps > Cowlendar Booking > Settings > Webhooks.

The Webhooks page

The table lists your endpoints with these columns:

Step 1: Add an endpoint

The signing secret is shown in full only once at creation. Store it securely. You will need it to verify incoming requests.

1. Open Settings > Webhooks.
2. Click Add endpoint.
3. In the window Add webhook, type a name in the Name field (up to 60 characters, for example Zapier sync). Then enter your server address in URL, which must use HTTPS. Under Events, tick each event you want to receive. Click Create.
4. Copy the signing secret and keep it safe.

Your endpoint must be a public HTTPS address that answers with a 2xx status within 10 seconds.

The 8 events

Every payload has id, type, created_at, shop_domain and data (the booking or the subscription).

Request headers

Every request Cowlendar sends has these headers:

Verify the signature

Always verify the signature before you trust a request.

1. Read the raw body of the request, exactly as received (do not parse and re-serialize it).
2. Read X-Cowlendar-Timestamp.
3. Build the text <timestamp>.<raw body>: the timestamp, a dot, then the raw body.
4. Calculate HMAC-SHA256 of that text with your signing secret.
5. Compare the result, in hex, with the v1= value of X-Cowlendar-Signature. Use a constant-time comparison.
6. Reject the request if the timestamp is more than 5 minutes old.

Node.js:

const crypto = require("crypto");

function verify(rawBody, timestamp, signatureHeader, secret) {
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = signatureHeader.split(",").find((p) => p.startsWith("v1=")).slice(3);
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python:

import hmac, hashlib, time

def verify(raw_body: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    message = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    received = next(p for p in signature_header.split(",") if p.startswith("v1="))[3:]
    return hmac.compare_digest(expected, received)

Retries

If your server does not answer with a 2xx within 10 seconds, Cowlendar retries the delivery: after 1 minute, 5 minutes, 25 minutes, 2 hours, 10 hours and 50 hours. After about 20 failures in a row, the endpoint is turned off automatically and its status changes to Inactive. Fix the problem and turn it on again with the play button.

Test and troubleshoot

• Test: sends a test request to your endpoint.
• See deliveries: shows the deliveries Cowlendar tried, to understand why one failed.
• Pause / play: turns an endpoint off or on.
• Edit and delete: change or remove an endpoint.

Quick fixes:

Related

• Public API (Beta): Generate Tokens and Read or Create Bookings
• Connect Cowlendar to CRM, ERP or App with the Public API and Webhooks
• Zapier Integration