Webhooks

Outbound webhooks let you receive real-time HTTP POST notifications when events occur in your project. Pro

Overview

Webhooks deliver a JSON payload to any HTTPS endpoint you configure whenever a specific event happens in your project. Each webhook can subscribe to one or more of the following events:

Webhooks are scoped to individual projects. Each project has its own set of webhook endpoints with independent configurations and signing secrets.

Configuring a webhook

1. Go to your project’s Integrations page
2. Scroll to the Outbound Webhooks section
3. Click Add webhook
4. Enter your endpoint URL (must be HTTPS in production)
5. Select which events to subscribe to
6. Click Save

After saving, a signing secret is displayed once. Copy it immediately — it cannot be retrieved later. You can regenerate it at any time from the webhook’s actions menu.

Verifying webhook signatures

Every webhook delivery includes an X-SupDesk-Signature header containing an HMAC-SHA256 signature of the request body. To verify a webhook:

1. Compute HMAC-SHA256(your_signing_secret, raw_request_body)
2. Compare the result with the hex value in the X-SupDesk-Signature header (after the sha256= prefix)
3. Use constant-time comparison to prevent timing attacks

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

Testing a webhook

Click the Test button next to a webhook to send a sample payload to its endpoint. The test payload has "event": "test" and a data.message field. Use a tool like webhook.site  to inspect the delivered request.

Delivery log

The Delivery log shows the last 50 delivery attempts for each webhook, including:

• Event — which event was delivered
• Status — success or failed
• Response code — HTTP status code from the endpoint
• Attempts — number of delivery attempts (including retries)
• Time — when the delivery was attempted

Retry behavior

When a webhook delivery fails (5xx response or network timeout), SupDesk retries up to 3 times with exponential backoff:

Client errors (4xx) are not retried — they indicate a permanent problem with the endpoint configuration.

Plan requirements

Outbound webhooks are available on Pro and Team plans.