Webhook Event Structure
All webhook events follow a consistent structure, making it easy to parse and handle events in your application.
Event Payload
Every webhook request contains a JSON payload with the following structure:
{
"event": "CONVERSATION_STARTED",
"eventId": "abc123-def456-ghi789",
"eventTimestamp": "2024-01-15T10:30:00.000Z",
"data": {
"recordId": "conv_abc123",
"organizationId": "org_xyz789"
// Additional event-specific data
},
"externalOrganizationId": "your_org_id"
}Payload Fields
| Field | Type | Description |
|---|---|---|
event | string | The event type (e.g., CONVERSATION_STARTED) |
eventId | string | Unique identifier for this event |
eventTimestamp | string | ISO 8601 timestamp when Popp prepared this webhook |
externalOrganizationId | string | Your own id for the organization the event came from. Omitted when none is set |
data | object | Event-specific data payload |
data.recordId | string | ID of the primary resource (conversation, candidate, etc.) |
data.organizationId | string | Your organization ID |
HTTP Headers
Each webhook request includes the following headers:
| Header | Description |
|---|---|
Content-Type | application/json |
x-signature | HMAC-SHA256 signature for verification (see Authentication) |
externalOrganizationId sits beside event, outside data: it tells you which organization the event came from, and data holds the event itself. It is not the same as data.externalId, which on candidate, list and conversation events is your own id for that record.
Example: Handling a Webhook
Verify the signature against the raw request body, before parsing it. See Authentication.
import crypto from 'crypto';
import express from 'express';
const verifyWebhookSignature = (rawBody: string, signature: string | undefined, signingSecret: string) => {
if (!signature) return false;
const expected = crypto.createHmac('sha256', signingSecret).update(rawBody).digest('hex');
return signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
};
const app = express();
app.post('/webhooks/popp', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8');
if (!verifyWebhookSignature(rawBody, req.header('x-signature'), signingSecret)) {
return res.status(401).send('Invalid signature');
}
const { event, eventId, eventTimestamp, data } = JSON.parse(rawBody);
console.log(`Received event: ${event}`);
console.log(`Event ID: ${eventId}`);
console.log(`Timestamp: ${eventTimestamp}`);
console.log(`Record ID: ${data.recordId}`);
console.log(`Organization ID: ${data.organizationId}`);
// Handle the event based on type
switch (event) {
case 'CONVERSATION_STARTED':
handleConversationStarted(data);
break;
case 'CONVERSATION_COMPLETED':
handleConversationCompleted(data);
break;
// ... handle other events
}
// Always respond with 200 to acknowledge receipt
res.status(200).send('OK');
});One Endpoint for Several Organizations
Each webhook has its own signing secret, and a webhook belongs to one organization. To receive events from several organizations at a single URL, register one webhook per organization pointing at that URL, and store each webhook's signing secret in a list under the organization's externalOrganizationId. Popp does not require external ids to be unique, so one id can hold the secrets of several webhooks.
The body is not trusted until the signature verifies, so use externalOrganizationId only as a hint for which secrets to try:
- Read the raw body and parse
externalOrganizationId. - Look up the signing secrets you stored for that id.
- Verify
x-signatureover the raw body with each secret in turn. If none matches, reject the request.
A request that names the wrong organization fails verification in step 3, so the hint cannot be used to forge an event.
app.post('/webhooks/popp', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8');
const hint = JSON.parse(rawBody).externalOrganizationId;
const signingSecrets = (hint && secretsByExternalOrganizationId.get(hint)) || [];
const signature = req.header('x-signature');
if (!signingSecrets.some((signingSecret) => verifyWebhookSignature(rawBody, signature, signingSecret))) {
return res.status(401).send('Invalid signature');
}
// Verified: one of the webhooks stored under that id sent it.
res.status(200).send('OK');
});Set an organization's externalOrganizationId with PATCH /v1/organizations/{id}. Until one is set, its events omit the field. Events from that organization can still be matched by data.organizationId.
Document Events
DOCUMENT_UPLOADED
DOCUMENT_UPLOADEDFires in real time whenever a candidate uploads a document during a conversation — you no longer have to wait for the conversation to complete to retrieve it. The event fires for every document a candidate sends (it is not limited to documents we successfully recognise).
In addition to the standard fields, data includes document metadata:
| Field | Type | Description |
|---|---|---|
data.recordId | string | The conversation ID the document was uploaded to |
data.attachmentId | string | ID of the stored attachment |
data.fileName | string | Original file name |
data.contentType | string | MIME type (e.g. application/pdf) |
data.classifiedDocumentType | string | What we classified the document as (e.g. passport), if recognised |
data.classifiedDocumentTypes | string[] | All candidate classifications, if more than one matched |
Checking document validity: this event is a notification that a document arrived; it does not include a pass/fail validity verdict. To decide whether a document is valid before ingesting it (e.g. to avoid pulling expired documents into your pipeline), call the processDocument endpoint with the document reference — it returns a structured verdict (passedValidation, validationErrors). Validity is computed on demand so it always reflects your current validation configuration.
Best Practices
- Respond quickly: Return a 200 response as soon as possible, then process the event asynchronously
- Handle duplicates: Events may be delivered more than once; use
eventIdfor idempotency - Verify signatures: Always verify the
x-signatureheader before processing - Log events: Store incoming events for debugging and audit purposes
Next Steps
- Conversation Events - Events for conversation lifecycle
- Analysis Events - Events for candidate analysis
- Scheduling Events - Events for calendar and meetings
Updated 14 days ago
