Webhooks API

Endpoints

Webhook Endpoint Object

{
  "id":          "wh_xxxx",
  "workspaceId": "ws_xxxx",
  "url":         "https://your-server.com/hooks/responsedock",
  "events":      ["survey.response.completed"],
  "isActive":    true,
  "createdAt":   "2024-11-14T10:00:00Z",
  "updatedAt":   "2024-11-14T10:00:00Z"
}

Create a Webhook Endpoint

POST /workspaces/:wid/webhooks

{
  "url":    "https://your-server.com/hooks/responsedock",
  "events": ["survey.response.started", "survey.response.completed"]
}

// 201 Created
{
  "webhook": {
    "id": "wh_yyyy",
    "url": "https://your-server.com/hooks/responsedock",
    "events": ["survey.response.started", "survey.response.completed"],
    "isActive": true,
    "createdAt": "2024-11-14T10:00:00Z"
  },
  "signingSecret": "whsec_xxxx"
}

Delivery Attempt Object

{
  "id":         "del_xxxx",
  "webhookEndpointId": "wh_xxxx",
  "eventType":  "survey.response.completed",
  "payload":    { "responseId": "resp_aaaa" },
  "status":     "SUCCESS",
  "httpStatus": 200,
  "attempts":   1,
  "lastAttemptAt": "2024-11-14T10:45:10Z",
  "nextRetryAt": null,
  "createdAt":  "2024-11-14T10:45:10Z"
}

Signature Verification

// Node.js / Express example
import crypto from 'crypto';

app.post('/hooks/responsedock', express.raw({ type: 'application/json' }), (req, res) => {
  const sig     = req.headers['x-survey-signature'] as string;
  const secret  = process.env.RESPONSEDOCK_WEBHOOK_SECRET!;
  const payload = req.body.toString();

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);
  // process event...
  res.json({ received: true });
});