Payload & Security

Payload Format

Every webhook delivers a JSON payload via HTTP POST:

{
  "id": "event-uuid",
  "type": "candidate_created",
  "subscriptionId": "your-subscription-id",
  "tenantId": "your-tenant-id",
  "eventTime": "2025-01-15T10:30:00.000+0000",
  "object": {
    "id": "record-id",
    "label": "Jane Doe",
    "type": "CANDIDATE"
  }
}

Fields

Field	Description
id	Unique event ID
type	The event code (e.g. candidate_created)
subscriptionId	Your webhook subscription ID
tenantId	Your Recruitly tenant ID
eventTime	ISO 8601 timestamp when the event occurred
object.id	The ID of the affected record
object.label	Display name of the record
object.type	Record type: CANDIDATE, JOB, CONTACT, LEAD, PLACEMENT

Signature Verification

Every webhook request includes an x-recruitly-signature header containing the unique signature assigned to your subscription.

// Node.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-recruitly-signature'];

  if (signature !== YOUR_SUBSCRIPTION_SIGNATURE) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const { type, object } = req.body;
  console.log(`${type}: ${object.label} (${object.id})`);

  res.status(200).send('OK');
});

Basic Authentication

You can configure HTTP basic authentication (username and password) on your endpoint during setup. Recruitly will include the credentials in the Authorization header of every request.