Webhooks

Build any integration you need. Webhooks send real-time HTTP notifications to any endpoint when events occur in Quackback. Connect to Zapier, your data warehouse, custom bots, or internal tools.

Overview

Webhooks are managed entirely through the REST API. Each webhook specifies:

• A URL to receive POST requests
• Which events to listen for
• Optional board filtering to scope events to specific boards
• A signing secret for verifying authenticity (HMAC-SHA256)

Create a webhook

[Your App] Create a webhook via the API:

curl -X POST https://feedback.example.com/api/v1/webhooks \
  -H "Authorization: Bearer qb_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["post.created", "post.status_changed"],
    "boardIds": ["board_01h455vb4pex5vsknk084sn02q"]
  }'

The response includes the signing secret, which is only shown once:

{
  "data": {
    "id": "webhook_01h455vb4pex5vsknk084sn02q",
    "url": "https://your-server.com/webhook",
    "secret": "whsec_...",
    "events": ["post.created", "post.status_changed"],
    "boardIds": ["board_01h455vb4pex5vsknk084sn02q"],
    "status": "active",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Warning: Store the secret immediately. It cannot be retrieved again. If you lose it, use the rotate endpoint to generate a new one.

Event Types

Note: Conversation and message events require the support inbox. Anonymous visitors' emails are never included (synthetic addresses are stripped). System messages (like "chat ended") are represented by conversation.* events rather than message.created, and internal-note deletions are not emitted.

Request Headers

Each webhook delivery includes these headers:

Payload Format

Every webhook delivery sends a JSON body with this structure:

{
  "id": "evt_a1b2c3d4e5f6...",
  "type": "post.created",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "data": {
    "post": {
      "id": "post_01h455vb4pex5vsknk084sn02q",
      "title": "Add dark mode support",
      "content": "It would be great to have a dark mode...",
      "boardId": "board_01h455vb4pex5vsknk084sn02q",
      "boardSlug": "feature-requests",
      "authorEmail": "[email protected]",
      "voteCount": 12
    }
  }
}

Signature Verification

[Your Server] Every webhook delivery is signed with HMAC-SHA256. Always verify the signature to confirm the request came from Quackback.

The signature is computed over \{timestamp\}.\{json_body\}:

import crypto from 'crypto';

function verifyWebhook(payload, signature, timestamp, secret) {
  const signaturePayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

// In your handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-quackback-signature'];
  const timestamp = req.headers['x-quackback-timestamp'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});

Tip: Also check that the timestamp is recent (within 5 minutes) to prevent replay attacks.

Board Filtering

Pass boardIds when creating a webhook to only receive events from specific boards. If omitted, the webhook receives events from all boards.

Note: Board filtering applies only to post and comment events. Conversation and message events aren't tied to a board, so a webhook with boardIds set still receives every chat event it subscribed to.

# Only events from a specific board
curl -X POST https://feedback.example.com/api/v1/webhooks \
  -H "Authorization: Bearer qb_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["post.created"],
    "boardIds": ["board_01h455vb4pex5vsknk084sn02q"]
  }'

Manage webhooks

List webhooks

curl https://feedback.example.com/api/v1/webhooks \
  -H "Authorization: Bearer qb_your_admin_key"

Update a webhook

curl -X PATCH https://feedback.example.com/api/v1/webhooks/webhook_01h4... \
  -H "Authorization: Bearer qb_your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["post.created", "comment.created"] }'

Rotate the signing secret

If a secret is compromised, rotate it:

curl -X POST https://feedback.example.com/api/v1/webhooks/webhook_01h4.../rotate \
  -H "Authorization: Bearer qb_your_admin_key"

The response contains the new secret. Update your server immediately.

Delete a webhook

curl -X DELETE https://feedback.example.com/api/v1/webhooks/webhook_01h4... \
  -H "Authorization: Bearer qb_your_admin_key"

Use Cases

Custom Slack Bot

Build a Slack bot with more control than the built-in integration:

app.post('/webhook', async (req, res) => {
  const { type, data } = req.body;

  if (type === 'post.created') {
    await slack.chat.postMessage({
      channel: '#feedback',
      text: `New feedback: ${data.post.title}`,
    });
  }

  res.sendStatus(200);
});

Zapier / n8n Integration

1. [Zapier / n8n] Create a Zap or n8n workflow with a webhook trigger
2. Copy the webhook URL
3. [Your App] Create a Quackback webhook pointing to that URL
4. [Zapier / n8n] Map fields in your automation tool

Data Warehouse Sync

Log events to your analytics platform:

app.post('/webhook', async (req, res) => {
  const { type, createdAt, data } = req.body;

  await db.insert('feedback_events', {
    event_type: type,
    event_time: createdAt,
    post_id: data.post?.id,
    raw_payload: JSON.stringify(data),
  });

  res.sendStatus(200);
});

Retry Behavior

Failed webhook deliveries are retried automatically:

• Attempts: Up to 3 delivery attempts per event
• Backoff: Exponential backoff starting at 1 second
• Retryable errors: Server errors (5xx), rate limits (429), and network timeouts
• Non-retryable errors: Client errors (4xx except 429) are not retried
• Timeout: Each delivery attempt has a 5-second timeout
• Auto-disable: After 50 consecutive permanent failures, the webhook is automatically disabled. The failure counter resets on each successful delivery.

Security Best Practices

1. Always verify signatures - reject unverified requests
2. Use HTTPS - never use HTTP endpoints for webhook receivers
3. Check timestamps - reject requests older than 5 minutes
4. Rotate secrets periodically - use the rotate endpoint
5. Respond quickly - return a 200 status within a few seconds; process asynchronously if needed

Next Steps

• API Overview - Full REST API documentation
• Integrations Overview - All available integrations
• Slack - Built-in Slack notification integration