Webhooks

Overview

Webhooks allow you to receive real-time notifications when events occur in WallJobs AI. Instead of polling the API, configure webhook endpoints to receive HTTP POST requests with event data automatically.

• Sync contacts to your CRM when created or updated
• Trigger workflows when candidates move through pipeline stages
• Update external systems when sequences complete or receive replies
• Build real-time dashboards and notifications

Setting Up Webhooks

Configure webhooks through the dashboard or API:

Via Dashboard

Via API

curl -X POST "https://api.walljobs.com.br/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/walljobs",
    "events": ["contact.created", "contact.updated", "shortlist.stage_changed"],
    "description": "Main CRM sync webhook"
  }'

{
  "data": {
    "id": "webhook_abc123",
    "url": "https://your-app.com/webhooks/walljobs",
    "events": ["contact.created", "contact.updated", "shortlist.stage_changed"],
    "description": "Main CRM sync webhook",
    "signing_secret": "whsec_abc123xyz789...",
    "status": "active",
    "created_at": "2024-01-22T18:00:00Z"
  }
}

Event Types

Subscribe to the events relevant to your integration:

Payload Format

All webhook payloads follow a consistent format:

{
  "id": "evt_abc123xyz789",
  "type": "contact.created",
  "created_at": "2024-01-22T18:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "id": "contact_def456",
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "maria@example.com",
    "created_at": "2024-01-22T18:30:00Z"
  }
}

• id - Unique event ID for idempotency
• type - The event type
• created_at - When the event occurred (ISO 8601)
• workspace_id - The workspace where the event occurred
• data - Event-specific data

Verifying Signatures

All webhook requests include a signature header for verification. Always verify signatures to ensure requests are from WallJobs AI.

The signature is in the X-WallJobs-Signature header and is computed as:

HMAC-SHA256(signing_secret, timestamp + "." + payload)

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhooks/walljobs', (req, res) => {
  const signature = req.headers['x-walljobs-signature'];
  const timestamp = req.headers['x-walljobs-timestamp'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhookSignature(payload, signature, timestamp, SIGNING_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

Retry Policy

If your endpoint returns a non-2xx status code or times out, we'll retry the webhook delivery:

• Retry 1: 1 minute after failure
• Retry 2: 5 minutes after first retry
• Retry 3: 30 minutes after second retry
• Retry 4: 2 hours after third retry
• Retry 5: 24 hours after fourth retry (final attempt)

After all retries fail, the webhook is marked as failed. You can manually retry failed webhooks from the dashboard.

Best Practices

• -
• -
• -

Webhook Endpoints

Manage webhooks via the API:

curl "https://api.walljobs.com.br/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "webhook_abc123",
      "url": "https://your-app.com/webhooks/walljobs",
      "events": ["contact.created", "contact.updated"],
      "status": "active",
      "created_at": "2024-01-22T18:00:00Z"
    }
  ]
}

curl -X DELETE "https://api.walljobs.com.br/v1/webhooks/webhook_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "id": "webhook_abc123",
    "deleted": true
  }
}