Skip to main content

API reference

Webhook event reference

Every event type Jobby.dev emits, when it fires, and the exact payload shape including idempotency keys.

Last updated

Every event Jobby.dev emits, when it fires, and the payload shape. Events fall into four categories: matchmaking, interview lifecycle, billing, and candidate flow.

Envelope

Every payload has the same outer shape:

{
  "id": "evt_abc123",         // unique per event; use as idempotency key
  "type": "match.matched",    // dotted-namespace event type
  "created_at": 1714780000,   // Unix seconds
  "data": { ... }             // event-specific shape
}

Matching events

Subscribe to any subset.

  • match.matched — fires when the matchmaker pairs a seeker with a recruiter and the match notification has been sent to both. data: match_id, seeker_id, recruiter_id, role_id, score.
  • match.accepted — fires when both sides have accepted and the room is opening. data: same shape as match.matched plus room_url.
  • match.declined — fires when either side declines. data: match_id, declined_by, reason.
  • match.expired — fires when neither side accepted within the 30-second window. data: match_id.

Interview events

  • interview.started — fires when the live room opens. data: match_id, room_url, started_at.
  • interview.completed — fires when the room closes (either side ended). data: match_id, duration_seconds, ended_by.
  • interview.report_card_submitted — fires when the recruiter completes the report card. data: match_id, decision (advance / pass / follow_up_async), ratings ({ fit, communication, technical_signal }).

Billing events

  • billing.subscription.upgraded — fires when a paid plan upgrade succeeds, hosted-checkout or off-session. data: from_plan, to_plan, interval, subscription_id.
  • billing.invoice.paid — fires on successful invoice payment. data: invoice_id, amount, currency, period_start, period_end.
  • billing.invoice.payment_failed — fires when an invoice charge fails. data: invoice_id, amount, currency, failure_code, retry_at.
  • billing.subscription.canceled — fires on cancellation (immediate or end-of-cycle). data: subscription_id, effective_at.

Candidate flow events

  • candidate.queued— fires when a seeker joins your event's queue. data: event_id, seeker_id, position.
  • candidate.left_queue — fires when a seeker leaves the queue without matching. data: event_id, seeker_id, reason (left / matched_elsewhere / event_ended).

Subscribing to a subset

On subscription create, pass the events array — a subscription with ["match.*"] would receive every match event but no interview, billing, or candidate events. Wildcards are supported per category prefix.

Versioning

Event payloads follow the same v1 contract as the REST API: no removed fields, no renamed types. New optional fields can land in existing event types; new event types can be added freely. Major versions go to /api/v2.

Related reading