Webhooks

Instead of polling, subscribe a URL to receive events as JSON POST requests the moment they happen.

Events

eventType	Fired when	Payload
new_interview	A new interview is created in your organization	The interview object (id, name, question_count, time_duration, questions, description)
candidate_status_changed	A candidate’s status is updated in the dashboard (for example, marked Selected)	The full response object (same shape as GET /responses items)
new_response	Reserved for future use; not currently sent	—

POST /subscribe

curl -X POST https://app.talvin.ai/api/v1/subscribe \
  -H "X-TALVIN-API-KEY: $TALVIN_API_KEY" \
  -H "X-TALVIN-ORGANIZATION-ID: $TALVIN_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "hookUrl": "https://your-app.example.com/webhooks/talvin",
    "eventType": "candidate_status_changed"
  }'

Response 201:

{ "id": "3d5a7e12-…" }

Store this subscription id. You need it to unsubscribe. Subscribe once per event type if you want more than one event.

DELETE /unsubscribe/{subscriptionId}

curl -X DELETE https://app.talvin.ai/api/v1/unsubscribe/3d5a7e12-… \
  -H "X-TALVIN-API-KEY: $TALVIN_API_KEY" \
  -H "X-TALVIN-ORGANIZATION-ID: $TALVIN_ORG_ID"

Returns 204 No Content on success.

Delivery: please read

• Events are sent as POST with Content-Type: application/json and a 5-second timeout. Respond with 200 quickly and do heavy processing in the background.
• Delivery is at-most-once: there are no automatic retries yet. If your endpoint is down when an event fires, that delivery is missed. Use GET /responses to catch up.
• Respond 410 Gone if you want Talvin to permanently switch the subscription off.
• Endpoints that keep failing may be switched off automatically. If events stop arriving, subscribe again.