Skip to main content

Webhook Events

This guide covers all available webhook events, their payloads, and when they're triggered.

Event Structure​

All webhook events follow a consistent structure:

{
    "event_type": "candidate.test_completed",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
        // Event-specific data
    },
    "metadata": {
        "webhook_id": "webhook-uuid",
        "delivery_id": "delivery-uuid"
    }
}

Common Fields​

  • event_type: The type of event that occurred
  • company_id: ID of the company where the event occurred
  • timestamp: ISO 8601 timestamp when the event was generated
  • data: Event-specific payload data
  • metadata: Additional information about the webhook delivery

Email Events​

email.sent​

Triggered when an email is successfully sent from DeePsy.

{
    "event_type": "email.sent",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {
        "email_id": "email-uuid",
        "recipient": "candidate@example.com",
        "subject": "Your Assessment Invitation",
        "template_type": "campaign_invitation",
        "campaign_id": "campaign-uuid",
        "candidate_id": "candidate-uuid"
    }
}

email.delivered​

Triggered when an email is successfully delivered to the recipient's inbox.

{
    "event_type": "email.delivered",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T10:32:15Z",
    "data": {
        "email_id": "email-uuid",
        "recipient": "candidate@example.com",
        "delivery_time": "2024-01-15T10:32:15Z",
        "smtp_response": "250 Message accepted"
    }
}

email.bounced​

Triggered when an email bounces (permanent delivery failure).

{
    "event_type": "email.bounced",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T10:33:00Z",
    "data": {
        "email_id": "email-uuid",
        "recipient": "invalid@example.com",
        "bounce_type": "hard",
        "bounce_reason": "Invalid recipient address",
        "smtp_code": "550"
    }
}

email.dropped​

Triggered when an email is dropped before sending (e.g., invalid format, blocked recipient).

{
    "event_type": "email.dropped",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T10:29:45Z",
    "data": {
        "email_id": "email-uuid",
        "recipient": "blocked@example.com",
        "drop_reason": "Recipient on suppression list",
        "drop_category": "suppressed"
    }
}

email.opened​

Triggered when a recipient opens an email.

{
    "event_type": "email.opened",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T11:15:30Z",
    "data": {
        "email_id": "email-uuid",
        "recipient": "candidate@example.com",
        "user_agent": "Mozilla/5.0...",
        "ip_address": "192.168.1.1",
        "location": {
            "city": "Paris",
            "country": "France"
        }
    }
}

email.clicked​

Triggered when a recipient clicks a link in an email.

{
    "event_type": "email.clicked",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T11:20:45Z",
    "data": {
        "email_id": "email-uuid",
        "recipient": "candidate@example.com",
        "url": "https://deepsy.fr/assessment/start/token",
        "user_agent": "Mozilla/5.0...",
        "ip_address": "192.168.1.1"
    }
}

Campaign Events​

campaign.created​

Triggered when a new assessment campaign is created.

{
    "event_type": "campaign.created",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T09:00:00Z",
    "data": {
        "campaign_id": "campaign-uuid",
        "name": "Software Developer Assessment",
        "description": "Technical assessment for developer positions",
        "creator_id": "user-uuid",
        "status": "draft",
        "settings": {
            "time_limit": 3600,
            "questions_count": 25,
            "passing_score": 70
        }
    }
}

campaign.updated​

Triggered when a campaign is modified.

{
    "event_type": "campaign.updated",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T14:30:00Z",
    "data": {
        "campaign_id": "campaign-uuid",
        "name": "Software Developer Assessment - Updated",
        "updated_fields": ["name", "description", "settings"],
        "updated_by": "user-uuid",
        "previous_values": {
            "name": "Software Developer Assessment"
        }
    }
}

campaign.archived​

Triggered when a campaign is archived.

{
    "event_type": "campaign.archived",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T16:00:00Z",
    "data": {
        "campaign_id": "campaign-uuid",
        "name": "Software Developer Assessment",
        "archived_by": "user-uuid",
        "archive_reason": "Campaign completed",
        "candidates_count": 45,
        "completed_count": 42
    }
}

Candidate Events​

candidate.created​

Triggered when a new candidate is added to a campaign.

{
    "event_type": "candidate.created",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T10:00:00Z",
    "data": {
        "candidate_id": "candidate-uuid",
        "campaign_id": "campaign-uuid",
        "email": "candidate@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "status": "invited",
        "created_by": "user-uuid"
    }
}

candidate.questionnaire_completed​

Triggered when a candidate completes the pre-assessment questionnaire.

{
    "event_type": "candidate.questionnaire_completed",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T11:30:00Z",
    "data": {
        "candidate_id": "candidate-uuid",
        "campaign_id": "campaign-uuid",
        "completion_time": "2024-01-15T11:30:00Z",
        "responses_count": 12,
        "time_taken_seconds": 420
    }
}

candidate.test_started​

Triggered when a candidate begins the assessment test.

{
    "event_type": "candidate.test_started",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T12:00:00Z",
    "data": {
        "candidate_id": "candidate-uuid",
        "campaign_id": "campaign-uuid",
        "test_session_id": "session-uuid",
        "start_time": "2024-01-15T12:00:00Z",
        "time_limit_seconds": 3600
    }
}

candidate.test_completed​

Triggered when a candidate completes the assessment test.

{
    "event_type": "candidate.test_completed",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T12:45:30Z",
    "data": {
        "candidate_id": "candidate-uuid",
        "campaign_id": "campaign-uuid",
        "test_session_id": "session-uuid",
        "completion_time": "2024-01-15T12:45:30Z",
        "time_taken_seconds": 2730,
        "questions_answered": 25,
        "questions_total": 25,
        "raw_score": 85.5
    }
}

candidate.evaluation_completed​

Triggered when the psychological evaluation and report generation is completed.

{
    "event_type": "candidate.evaluation_completed",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T13:00:00Z",
    "data": {
        "candidate_id": "candidate-uuid",
        "campaign_id": "campaign-uuid",
        "evaluation_id": "evaluation-uuid",
        "final_score": 87.2,
        "percentile": 92,
        "report_available": true,
        "report_url": "https://deepsy.fr/reports/evaluation-uuid",
        "processing_time_seconds": 45
    }
}

User Events​

user.created​

Triggered when a new user account is created.

{
    "event_type": "user.created",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T08:30:00Z",
    "data": {
        "user_id": "user-uuid",
        "email": "newuser@company.com",
        "first_name": "Jane",
        "last_name": "Smith",
        "role": "hr_manager",
        "created_by": "admin-user-uuid"
    }
}

user.invited​

Triggered when a user is invited to join a company.

{
    "event_type": "user.invited",
    "company_id": "company-uuid",
    "timestamp": "2024-01-15T09:15:00Z",
    "data": {
        "invitation_id": "invitation-uuid",
        "email": "invited@company.com",
        "role": "recruiter",
        "invited_by": "admin-user-uuid",
        "expires_at": "2024-01-22T09:15:00Z"
    }
}

Event Filtering​

When creating webhooks, you can subscribe to specific events:

// Subscribe to all candidate events
const candidateEvents = [
    'candidate.created',
    'candidate.questionnaire_completed',
    'candidate.test_started',
    'candidate.test_completed',
    'candidate.evaluation_completed'
];

// Subscribe to email delivery events only
const emailEvents = [
    'email.sent',
    'email.delivered',
    'email.bounced'
];

// Subscribe to campaign lifecycle events
const campaignEvents = [
    'campaign.created',
    'campaign.updated',
    'campaign.archived'
];

Handling Events​

Processing Guidelines​

  1. Acknowledge Receipt: Always return HTTP 200 status code
  2. Process Asynchronously: Queue events for background processing if needed
  3. Handle Duplicates: Events may be delivered more than once
  4. Validate Data: Always validate event data before processing
  5. Log Events: Keep logs for debugging and audit purposes

Example Event Handler​

function handleWebhookEvent(event) {
    switch (event.event_type) {
        case 'candidate.test_completed':
            handleTestCompletion(event.data);
            break;
        case 'email.bounced':
            handleEmailBounce(event.data);
            break;
        case 'campaign.created':
            handleCampaignCreation(event.data);
            break;
        default:
            console.log('Unknown event type:', event.event_type);
    }
}

Continue to our Security Guide to learn about webhook signature verification.