Webhooks

Webhooks are available to send updates to a specified url for your organization when changes take place.

Available Webhook Event Types

Webhook EventDescription
PROJECTS.UPDATEDWhen the recruitingStatus of the project changes.
SCREENER_RESPONSES.CREATEDWhen a new screener response has been submitted by a participant.
SCREENER_RESPONSES.UPDATEDWhen a screener response has been updated by a participant. Non-researcher actions. Including status change to PAID or CANCELLED.

To Setup a webhook

  • Create a POST to /v1/webhooks with the desired url for webhooks to be sent to.
    • {"url": "https://my-webhooks.com"}
      
    • This will return a body with the id, url, and a privateKey to be used to validate webhook responses
      {
        "id": "6668c6892df38f2e720c97d6",
        "url": "https://my-webhooks.com",
        "privateKey": "74e811b4-a1cc-4fa7-857b-0df0fce9a5a9"
      }
      

To Validate a webhook signature

const signatureHeader = request.headers['Respondent-Webhook-Signature'];
const body = request.body;
const algorithm = signatureHeader.substring(0, signatureHeader.indexOf('='));
const receivedSignature = signatureHeader.replace(algorithm + '=', '');
const privateKey = '<privateKey>';

const hmacBodyDigest = createHmac(algorithm, privateKey)
    .update(JSON.stringify(body))
    .digest('base64');

if (hmacBodyDigest === receivedSignature) {
    // Handle webhook events
    return HttpStatusCode.Ok;
  } else {
    return HttpStatusCode.Forbidden;
  }

Visit our API Reference for more details:

https://developers.respondent.io/reference/webhookscontroller_create