Documentation

Overview

Webhooks are HTTP callbacks that are triggered when specific events occur in the AutoTechJobs system. When an event happens, we'll send an HTTP POST request to the URL you've configured, containing information about the event.

Common Use Cases

• Receive notifications when new applications are submitted for your job listings
• Update your CRM or ATS when candidate statuses change
• Trigger automated workflows when new jobs are posted
• Sync job data with your internal systems
• Get notified when a candidate accepts or rejects an offer

Setting Up Webhooks

Create a Webhook Endpoint

Register a new webhook endpoint to receive event notifications.

Request Body

Example Request

curl -X POST   "https://api.autotechjobs.co.uk/v1/webhooks"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://your-app.example.com/webhooks/autotechjobs",
    "events": ["job.created", "application.submitted", "application.status_updated"],
    "description": "Webhook for job and application events"
  }'

Example Response

{
  "data": {
    "id": "wh_123456",
    "url": "https://your-app.example.com/webhooks/autotechjobs",
    "events": ["job.created", "application.submitted", "application.status_updated"],
    "description": "Webhook for job and application events",
    "secret": "whsec_abcdefghijklmnopqrstuvwxyz1234567890",
    "status": "active",
    "created_at": "2025-04-10T20:32:13Z"
  }
}

Event Types

The following event types are available for webhook subscriptions:

Webhook Payloads

When an event occurs, we'll send an HTTP POST request to your webhook URL with a JSON payload containing information about the event.

Payload Structure

All webhook payloads have the following structure:

{
  "id": "evt_123456",            // Unique event ID
  "type": "application.submitted", // Event type
  "created_at": "2025-04-10T20:32:13Z", // When the event occurred
  "data": {                     // Event-specific data
    // Varies based on event type
  }
}

Example Payload: application.submitted

{
  "id": "evt_123456",
  "type": "application.submitted",
  "created_at": "2025-04-10T20:32:13Z",
  "data": {
    "application": {
      "id": "app_789012",
      "job": {
        "id": "job_123456",
        "title": "Senior React Developer",
        "company": "Tech Innovations Ltd"
      },
      "candidate": {
        "id": "cand_789012",
        "name": "Jane Smith",
        "email": "[email protected]"
      },
      "status": "pending",
      "applied_at": "2025-04-10T20:32:13Z"
    }
  }
}

Verifying Webhook Signatures

To ensure that webhook requests are coming from AutoTechJobs and not a third party, we sign all webhook requests with a signature. You should verify this signature before processing the webhook data.

Signature Header

Each webhook request includes an X-AutoTechJobs-Signature header with a timestamp and a signature. The format is: t=timestamp,v1=signature

Verification Process

1. Extract the timestamp and signature from the header
2. Verify that the timestamp is not too old (to prevent replay attacks)
3. Create a string by concatenating the timestamp, a period (.), and the raw request body
4. Compute an HMAC with SHA-256 using your webhook secret as the key and the string from step 3 as the message
5. Compare the computed signature with the signature from the header

Code Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, header, secret) {
  // Extract timestamp and signature from header
  const [timestamp, signature] = header.split(',');
  const timestampValue = timestamp.split('=')[1];
  const signatureValue = signature.split('=')[1];
  
  // Check if the timestamp is too old (more than 5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (now - parseInt(timestampValue) > 300) {
    return false; // Timestamp too old
  }
  
  // Create the string to sign
  const signedPayload = `${timestampValue}.${payload}`;
  
  // Compute the signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  // Compare signatures
  return crypto.timingSafeEqual(
    Buffer.from(signatureValue),
    Buffer.from(expectedSignature)
  );
}

Managing Webhooks

List Webhooks

Retrieve all webhooks for your account.

Update a Webhook

Update an existing webhook configuration.

Delete a Webhook

Delete a webhook endpoint.

Best Practices

• Always verify signatures: This ensures that webhook requests are coming from AutoTechJobs and not a malicious third party.
• Implement idempotency: Webhook events may be delivered more than once in rare cases. Design your webhook handler to be idempotent to avoid processing the same event multiple times.
• Respond quickly: Your webhook endpoint should acknowledge receipt of the webhook by returning a 2xx status code as quickly as possible. Process the webhook data asynchronously if needed.
• Handle failures gracefully: If your webhook endpoint fails to process an event, we'll retry delivery with an exponential backoff schedule.
• Monitor webhook deliveries: You can view webhook delivery history in the AutoTechJobs dashboard to troubleshoot any issues.
• Use HTTPS: All webhook URLs must use HTTPS to ensure secure data transmission.