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

FieldTypeDescription
eventstringThe event type (e.g., CONVERSATION_STARTED)
eventIdstringUnique identifier for this event
eventTimestampstringISO 8601 timestamp when Popp prepared this webhook
externalOrganizationIdstringYour own id for the organization the event came from. Omitted when none is set
dataobjectEvent-specific data payload
data.recordIdstringID of the primary resource (conversation, candidate, etc.)
data.organizationIdstringYour organization ID

HTTP Headers

Each webhook request includes the following headers:

HeaderDescription
Content-Typeapplication/json
x-signatureHMAC-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:

  1. Read the raw body and parse externalOrganizationId.
  2. Look up the signing secrets you stored for that id.
  3. Verify x-signature over 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

Fires 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:

FieldTypeDescription
data.recordIdstringThe conversation ID the document was uploaded to
data.attachmentIdstringID of the stored attachment
data.fileNamestringOriginal file name
data.contentTypestringMIME type (e.g. application/pdf)
data.classifiedDocumentTypestringWhat we classified the document as (e.g. passport), if recognised
data.classifiedDocumentTypesstring[]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

  1. Respond quickly: Return a 200 response as soon as possible, then process the event asynchronously
  2. Handle duplicates: Events may be delivered more than once; use eventId for idempotency
  3. Verify signatures: Always verify the x-signature header before processing
  4. Log events: Store incoming events for debugging and audit purposes

Next Steps


Did this page help you?