Webhooks¶

Webhooks let you receive real-time notifications when events occur in SpeakNode. When an event triggers, the platform sends an HTTP POST request to your specified URL with the event payload.

Creating a Webhook Subscription¶

1. Navigate to Webhooks in the sidebar.
2. Click + Create Webhook.
3. Fill in the configuration:
   • URL: The endpoint where SpeakNode will send event payloads (e.g., https://your-server.com/webhooks/speaknode).
   • Description: A note describing the purpose of this webhook (e.g., "CRM sync for completed conversations").
   • Event Types: Select which events should trigger this webhook.
   • Enabled: Toggle the webhook on or off.
4. Click Save.

Event Types¶

Webhook Secret and Signature Verification¶

Each webhook subscription is assigned a Webhook Secret. Use this secret to verify that incoming requests genuinely originate from SpeakNode.

How Verification Works¶

SpeakNode signs each webhook request using HMAC-SHA256:

1. The platform computes an HMAC-SHA256 hash of the request body using your webhook secret as the key.
2. The resulting signature is included in the request header.
3. Your server should compute the same hash and compare it to the header value.

Verification Example¶

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Viewing Request History¶

SpeakNode logs every webhook delivery attempt so you can debug issues.

1. Open a webhook subscription from the Webhooks list.
2. Scroll down to the Request History section.
3. Each entry shows:
   • Timestamp: When the request was sent.
   • HTTP Status: The response status code from your server (e.g., 200, 500, timeout).
   • Payload: The JSON body that was sent.
   • Response: The response body returned by your server.

Troubleshooting¶