Webhooks

Events, payloads, signatures and retries.

Add an endpoint in the console and choose its events. Each delivery is a POST with a JSON body and a DialerSeat-Signature header.

Events

• seat.activated: A seat can dial: payment went through, or the platform covers it.
• seat.payment_failed: A user-billed seat's weekly charge failed. Dialing stops at the end of the paid days.
• seat.disabled: A seat stopped: cancelled, or disabled through the API.
• call.started: A line started ringing.
• call.answered: The lead answered and is connected to the agent. amd_result is pending while answering-machine detection is still listening, or not_run when it is off.
• call.ended: The call ended. Includes duration, talk seconds, who hung up (lead, agent, amd, no_answer, busy, failed, agent_unreachable) and the final AMD result.
• call.dispositioned: The agent picked a disposition. Your code, your label, our outcome class.
• recording.ready: A recording is stored and can be fetched.
• lead.exhausted: A lead used every attempt the campaign allows.
• campaign.completed: Every lead in a campaign is dialled or exhausted.

Verifying a signature

The header is t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" with your endpoint's signing secret>. Reject deliveries more than five minutes old.

import crypto from 'node:crypto'

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}

Retries

Anything but a 2xx within 10 seconds is retried with backoff for 72 hours. Every delivery has an id; process each id once.