Webhooks

Available Webhook Event Types

Webhook Event	Description
`PROJECTS.UPDATED`	When the `recruitingStatus` of the project changes.
`SCREENER_RESPONSES.CREATED`	When 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;
  }

Visit our API Reference for more details:

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