Webhook events are sent only for projects created via API

​
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.UPDATED- When a screener response has been updated by a participant. Non-researcher actions. Including status change to PAID or CANCELLED. - When a screener is rejected and no longer visible, or approved and made visible again

​
Webhook Body Examples

​
Project updated - started recruiting for first time

{
  event: 'PROJECTS.UPDATED',
  uuid: '015d7dbb-3f6b-4446-a1d3-0336ac91b320',
  created: '2024-08-28T22:20:04.248Z',
  payload: {
    resource: {
      id: '66cfaf354b3f22e42ac79a92',
      type: 'projects',
      updatedFields: [
        {
          name: 'recruitingStatus',
          newValue: 'RECRUITING',
        },
      ],
    },
  },
}

​
Screener response created

{
  event: 'SCREENER_RESPONSES.CREATED',
  uuid: '015d7dbb-3f6b-4446-a1d3-0336ac91b320',
  created: '2024-08-28T22:20:04.248Z',
  payload: {
    resource: {
      id: '66cf97060888f40f25b78ab4',
      parentId: '66cf96ce0888f40f25b78297',
      type: 'screener-responses',
    },
  },
}

​
Screener response status updated

{
  event: 'SCREENER_RESPONSES.UPDATED',
  uuid: '67ec23b8-4016-42cc-933d-073d141d8e76',
  created: '2024-08-28T22:20:04.248Z',
  payload: {
    resource: {
      id: '66cf97060888f40f25b78ab4',
      parentId: '66cf96ce0888f40f25b78297',
      type: 'screener-responses',
      updatedFields: [
        {
          name: 'status',
          oldValue: 'ATTENDED',
          newValue: 'PAI',
        },
      ],
    },
  },
}

​
Screener Response rejected (will no longer be visible in api)

{
  event: 'SCREENER_RESPONSES.UPDATED',
  uuid: '67ec23b8-4016-42cc-933d-073d141d8e76',
  created: '2024-08-28T22:20:04.248Z',
  payload: {
    resource: {
      id: '66cf97060888f40f25b78ab4',
      parentId: '66cf96ce0888f40f25b78297',
      type: 'screener-responses',
      updatedFields: [
        {
          name: 'rejected',
          oldValue: false,
          newValue: true,
        },
      ],
    },
  },
}

​
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;
  }

​
Webhook responses and retries

Partners must return a 2xx status code within 3 seconds; otherwise, we’ll retry up to 5 times in 10-minute intervals.