Webhooks - Hotfix Jobs

A webhook sends hiring events to a URL you own: a new application, a booked interview, an accepted offer. Use it to post to Slack, update a sheet, or start your own workflow. Nothing to poll.

Add a webhook

Owners and admins manage webhooks in the app under Settings > API > Webhooks. Members can see them and their delivery log, but can’t change them.

Click New webhook.
Enter an https URL.
Keep All events, or pick the events this URL should get.
Click Add webhook and copy the signing secret. It is shown once.

A company can have up to 10 webhooks. Each one has its own URL, its own events, and its own secret, so you can send offers to one system and everything to another. Open a webhook to change its URL or events. That keeps the same secret. Rotate secret issues a new one and shows it once; deliveries sign with it right away. Send test event posts a signed ping to the URL and shows the response.

Events

Pick All events to also get events added later.

Event	Sent when
`application.confirmed`	A new application lands in the inbox (after the candidate confirms, if your apply form asks them to).
`interview.booked`	An interview is booked, by the candidate on their link or by your team.
`interview.rescheduled`	Your team moves an interview.
`interview.moved`	The candidate moves an interview on their link.
`interview.canceled`	An interview is canceled.
`feedback.submitted`	Someone on an interview adds their feedback (not when they edit it).
`feedback.completed`	Everyone on an interview has added their feedback. Sent once per interview.
`offer.created`	Your team creates an offer.
`offer.accepted`	The candidate accepts an offer.
`offer.declined`	The candidate declines an offer.
`job.listed`	A tech job goes onto Hotfix search, once Hotfix has read it. Not sent again after an edit, since a listed job stays on search.
`job.closed`	A job closes.
`ping`	You click Send test event.

The request

Every delivery is a POST with a JSON body:

{
  "event": "application.confirmed",
  "data": {
    "application_id": "7cbfa03e-70c6-4463-8e10-376e2221ec51",
    "job_id": "1f0c2a9e-3b6d-4c8a-9a51-6a2f0c9d1e77",
    "job_title": "iOS Engineer",
    "company_name": "Acme",
    "company_slug": "acme",
    "applicant_name": "Ada Lovelace",
    "applicant_email": "ada@example.com",
    "custom_fields": [
      {
        "id": "4b8e…",
        "key": "salary_expectation",
        "name": "Salary expectation",
        "type": "currency",
        "value": "140000",
        "display": "$140,000"
      }
    ]
  }
}

Events about an application carry the fields above, with custom_fields in the same shape as applications. Some add a little more:

Event	Also in `data`
`interview.booked`	`interview_id`, and `starts_at` when the candidate picked the time
`interview.rescheduled`, `interview.canceled`	`interview_id`
`interview.moved`	`interview_id`, `starts_at`, `previous_starts_at`
`feedback.submitted`	`interview_id`, `stage`, `submitted_by` (a user id). No verdict.
`feedback.completed`	`interview_id`, `stage`, and `feedback` (see below)
`offer.created`	`pay`, `start_date`
`offer.accepted`	`offer_id`, `accepted_as` (the name they typed)
`offer.declined`	`offer_id`

feedback.submitted never carries a verdict, since someone else on the panel may not have added theirs yet. feedback.completed comes once nothing is hidden from anyone on the panel, so feedback lists each person’s user_id, name, verdict (strong_no, no, yes, or strong_yes), and ratings on the job’s interview criteria (id, name, rating, which is null for a skipped criterion). Notes are left out; read them with list_feedback. Neither is sent while your company has interview feedback turned off.

{
  "event": "feedback.completed",
  "data": {
    "interview_id": "b1c2d3e4-f5a6-7890-1234-56789abcdef0",
    "stage": "technical",
    "feedback": [
      {
        "user_id": "user_2abc",
        "name": "Alex Park",
        "verdict": "strong_yes",
        "ratings": [
          {
            "id": "c_1a2b3c4d",
            "name": "System design",
            "rating": "strong_yes"
          }
        ]
      },
      {
        "user_id": "user_9xyz",
        "name": "Priya Shah",
        "verdict": "no",
        "ratings": [
          { "id": "c_1a2b3c4d", "name": "System design", "rating": "yes" }
        ]
      }
    ],
    "application_id": "7cbfa03e-70c6-4463-8e10-376e2221ec51",
    "job_id": "1f0c2a9e-3b6d-4c8a-9a51-6a2f0c9d1e77",
    "job_title": "iOS Engineer",
    "company_name": "Acme",
    "company_slug": "acme",
    "applicant_name": "Ada Lovelace",
    "applicant_email": "ada@example.com",
    "custom_fields": []
  }
}

Job events send only job_id and job_title. A ping sends webhook_id and company_id. Each request has these headers:

Header	Value
`X-Hotfix-Event`	The event name.
`X-Hotfix-Delivery`	The delivery id. The same on every retry of that delivery.
`X-Hotfix-Timestamp`	Unix seconds when this attempt was signed.
`X-Hotfix-Signature`	`v1=` and a hex HMAC-SHA256.

Verify the signature

The signature is an HMAC-SHA256 of the timestamp, a period, and the raw request body, keyed with the webhook’s secret. Compute it over the bytes you received, before parsing the JSON, and compare in constant time. Reject a timestamp more than five minutes from your clock, so an old request can’t be replayed.

import crypto from "node:crypto";

export function verify(rawBody, headers, secret) {
  const timestamp = headers["x-hotfix-timestamp"];
  const signature = headers["x-hotfix-signature"] ?? "";
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.`)
      .update(rawBody)
      .digest("hex");
  return (
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  );
}

import hashlib
import hmac
import time


def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Hotfix-Timestamp", "")
    signature = headers.get("X-Hotfix-Signature", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Respond and retries

Answer with any 2xx within 10 seconds. Do slow work after you respond. Anything else counts as a failure. Hotfix tries a delivery up to 5 times, waiting 1 minute, 5 minutes, 30 minutes, then 2 hours between tries. After the fifth failure the delivery shows as failed. A test event is not retried. Because of retries, you can get the same delivery more than once. Use X-Hotfix-Delivery to drop repeats. Deliveries can also arrive out of order, so read starts_at and the current state instead of assuming the order you receive them in.

Delivery log

Open a webhook to see its last deliveries: the event, whether it was delivered, the response code, how many tries it took, and the error when it failed.

​Add a webhook

​Events

​The request

​Verify the signature

​Respond and retries

​Delivery log