Webhook events are sent only for projects created via API
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
{
"event": "SCREENER_RESPONSES.CREATED",
"uuid": "006a4577-43d6-448a-a3d6-1a63581ca217",
"created": "2026-01-08T23:09:08.239Z",
"payload": {
"resource": {
"id": "69603913cd7d6158385a1ff7",
"parentId": "69603913cd7d6158385a1ff6",
"type": "screener-responses"
}
}
}
Screener response status updated
{
"event": "SCREENER_RESPONSES.UPDATED",
"uuid": "b7d8bc55-28dd-4319-b25a-84a7558afccf",
"created": "2026-01-08T23:09:22.735Z",
"payload": {
"resource": {
"id": "69603922bd5465b2dd6bd6e7",
"parentId": "69603922bd5465b2dd6bd6e6",
"type": "screener-responses",
"updatedFields": [
{
"name": "status",
"oldValue": "PENDING",
"newValue": "CANCELLED"
}
]
}
}
}
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 will be available in staging on January 14, 2026 and in
production on 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.
