Webhooks Overview

Webhook events are sent only for projects created via API

Each team can have a single active webhook, which receives all events for projects created under that team. (A team can have multiple sets of API credentials; they all share the same webhook.)

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. Includes status change to `PAID` or `CANCELLED` and when a screener is rejected and no longer visible, or approved and made visible again.
`MESSAGES.CREATED`	Any new messages from participants.
`CONVERSATIONS.CREATED`	Any new conversation created.

Webhook Body Examples

Project updated

{
  "event": "PROJECTS.UPDATED",
  "uuid": "4aae25da-dd7b-4e2d-bb6a-9177dec83baa",
  "created": "2026-01-08T23:09:42.677Z",
  "payload": {
    "resource": {
      "id": "69603934cd7d6158385a200c",
      "type": "projects",
      "updatedFields": [
        {
          "name": "recruitingStatus",
          "oldValue": "RECRUITING",
          "newValue": "RECRUITED"
        }
      ]
    }
  }
}

Screener response created

Deprecation Notice: The parentId field in screener response created webhook events is deprecated. Please use projectId instead. parentId will be removed in February 2027.

{
  "event": "SCREENER_RESPONSES.CREATED",
  "uuid": "006a4577-43d6-448a-a3d6-1a63581ca217",
  "created": "2026-01-08T23:09:08.239Z",
  "payload": {
    "resource": {
      "id": "69603913cd7d6158385a1ff7",
      "projectId": "69603913cd7d6158385a1ff6",
      "type": "screener-responses"
    }
  }
}

Screener response status updated

Deprecation Notice: The parentId field in screener response webhook updated events is deprecated. Please use projectId instead. parentId will be removed in February 2027.

{
  "event": "SCREENER_RESPONSES.UPDATED",
  "uuid": "b7d8bc55-28dd-4319-b25a-84a7558afccf",
  "created": "2026-01-08T23:09:22.735Z",
  "payload": {
    "resource": {
      "id": "69603922bd5465b2dd6bd6e7",
      "projectId": "69603922bd5465b2dd6bd6e6",
      "type": "screener-responses",
      "updatedFields": [
        {
          "name": "status",
          "oldValue": "PENDING",
          "newValue": "CANCELLED"
        }
      ]
    }
  }
}

SCREENER_RESPONSES.CREATED webhook payloads carry only resource IDs. SCREENER_RESPONSES.UPDATED webhook payloads carry resource IDs plus the changed fields under updatedFields. To read the full screener response, fetch it via GET /v1/projects/{projectId}/screener-responses/{screenerResponseId}.

Messaging Webhooks

Messaging webhooks notify you when participants send messages or when new conversations are created. These events are only triggered for messages sent by participants, not by researchers.

Messaging webhooks are available in staging (since January 14, 2026) and in production (since February 11, 2026).

Message created

Triggered when a participant sends a message in a conversation.

{
  "event": "MESSAGES.CREATED",
  "uuid": "4e5aa6de-70f9-4973-b50b-a05b9b79dfdb",
  "created": "2026-01-08T23:07:25.251Z",
  "payload": {
    "resource": {
      "messageId": "fe8edd40-92c8-4feb-bc71-8aea41a7de1e",
      "messageBody": "Test Message",
      "attachments": [
        {
          "uid": "a1f7b0bb-b1ef-4110-84d5-aaedbcdb5abd",
          "url": "https://respondentinc-attachments.s3.amazonaws.com/1764563749874_4ab5ba94-0ec4-4202-b0c7-c3aae37110b3_file_name.pdf?1764563751101",
          "contentType": "application/pdf"
        }
      ],
      "projectId": "6927a28e6f6ab200a4c358a7",
      "conversationId": "04576ba9-2309-4f3b-82b4-2771fe737085",
      "senderType": "participant",
      "profileId": "67d763cfa53ea24550dc52b2",
      "organizationId": "67c4f87adbb9ff9dc5322fc8",
      "teamId": "67c4f87adbb9ff9dc5322fe0",
      "webhookId": "6960367acd7d61583859e0e0",
      "createdAt": "2026-01-08T23:06:08.603Z",
      "updatedAt": "2026-01-08T23:06:08.603Z"
    }
  }
}

Conversation created

Triggered when a new conversation is created with a participant. Includes the full conversation object, participant profiles, and the initial message if present.

{
  "event": "CONVERSATIONS.CREATED",
  "uuid": "ede25382-a2e4-4a81-b591-a311ec302e4f",
  "created": "2026-01-08T23:08:28.975Z",
  "payload": {
    "resource": {
      "conversation": {
        "uid": "04576ba9-2309-4f3b-82b4-2771fe737085",
        "name": "Conversation Test",
        "deleted": false,
        "locked": false,
        "read": false,
        "createdAt": "2025-12-01T02:34:41.004Z",
        "updatedAt": "2025-12-01T02:34:41.008Z",
        "metadata": {
          "projectId": "6927a28e6f6ab200a4c358a7",
          "researcherUserId": "67c4f86584754023ca2ec3ec",
          "externalResearcherId": "externalResearcherId"
        },
        "user": {
          "uid": "2bc828db-e6f6-481e-af8d-2860153a31b0",
          "foreignId": "67d763ceb7852780e7fbb68e",
          "firstName": "John",
          "lastName": "S"
        },
        "participants": [
          {
            "uid": "fe799a09-08ac-4486-8dee-4f69dc1b5153",
            "foreignId": "67c4f86584754023ca2ec3ec",
            "firstName": "Sam",
            "lastName": "D",
            "read": true,
            "deleted": false
          },
          {
            "uid": "2bc828db-e6f6-481e-af8d-2860153a31b0",
            "foreignId": "67d763ceb7852780e7fbb68e",
            "firstName": "John",
            "lastName": "S",
            "read": true,
            "deleted": false
          }
        ]
      },
      "organizationId": "67c4f87adbb9ff9dc5322fc8",
      "teamId": "67c4f87adbb9ff9dc5322fe0",
      "webhookId": "6960367acd7d61583859e0e0"
    }
  }
}

To set up 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 your organizationId, teamId, url, privateKey, and the webhook id to be used to validate webhook responses

{
  "organizationId": "67c4f87adbb9ff9dc5322fc8",
  "teamId": "67c4f87adbb9ff9dc5322fe0",
  "url": "https://webhook.site/7d91c565-0f90-4340-8774-f3131f61606c",
  "privateKey": "44450f9c-f43c-4c26-98cb-53bdc0f49fde",
  "id": "6960367acd7d61583859e0e0"
}

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.

Isolating your own environments on staging

Because each team has its own independent webhook, you can use separate teams to represent your own development and staging environments against the Respondent staging environment. Create a team for each environment (for example, one per developer’s local stack or a shared CI environment), each with its own API credentials, and register a webhook on each. Deliveries for one environment then never collide with another’s, so you can test webhook handling in isolation.

Getting started

Projects

Screeners and Responses

Messaging

Webhooks

Guides

Available Webhook Event Types

Webhook Body Examples

Project updated

Screener response created

Screener response status updated

Messaging Webhooks

Message created

Conversation created

To set up a webhook

To Validate a webhook signature

Webhook responses and retries

Isolating your own environments on staging

​Available Webhook Event Types

​Webhook Body Examples

​Project updated

​Screener response created

​Screener response status updated

​Messaging Webhooks

​Message created

​Conversation created

​To set up a webhook

​To Validate a webhook signature

​Webhook responses and retries

​Isolating your own environments on staging

Available Webhook Event Types

Webhook Body Examples

Project updated

Screener response created

Screener response status updated

Messaging Webhooks

Message created

Conversation created

To set up a webhook

To Validate a webhook signature

Webhook responses and retries

Isolating your own environments on staging