Webhooks

New Call

This webhook is sent when a new call is created on the platform, it is configured at the appplication level

Authentication

AuthorizationBasic

Basic authentication of the form Basic <base64(username:password)>.

Request

Information about a new call
call_sidstringRequired
a unique identifier for the call.
call_idstringRequired
the call id in our server.
application_sidstringRequired
a unique identifier for the jambonz application controlling this call
account_sidstringRequired
a unique identifier for the jambonz account associated with the application
directionenumRequired

the direction of the call:

  • inbound - The call was originated outside jambonz
  • outbound - The call was originated by jambonz
fromstringRequired
the calling party number
tostringRequired
the called party number
caller_namestringRequired
the caller name, if known
sip_statusdoubleRequired
the most recent sip status code received or generated for the call
sip_reasonstringRequired

the reason phrase from the SIP status LINE of the last response (e.g. Trying, OK, Busy Here). This is not the RFC 3326 Reason header - see sip_reason_header.

call_statusenumRequired

current status of the call:

  • trying - a new incoming call has arrived or an outbound call has just been sent
  • ringing - a 180 Ringing response has been sent or received
  • early-media - an early media connection has been established prior to answering the call (183 Session Progress)
  • in-progress - call has been answered
  • completed - an answered call has ended
  • failed - a call attempt failed
  • busy - a call attempt failed because the called party returned a busy status
  • no-answer - a call attempt failed because it was not answered in time
sip_reason_headerstringOptional

the RFC 3326 Reason header of the SIP message that caused this status change, if it carried one; omitted otherwise.

Carriers fronting ISDN/E1 PRI trunks put the authoritative disconnect cause here rather than in the status line, and the same SIP status can carry different causes - a 503 may be cause=38 (network out of order) or cause=41 (temporary failure) - so the status code alone cannot classify the outcome of a call. A 408 with Q.850;cause=18 (“no user responding”) is a call nobody answered, not a platform fault.

Present on whichever event observed it: a final failure response, a BYE on an answered call, or a CANCEL from a caller who gave up. The CANCEL case matters most, because the 487 and its Request Terminated phrase are generated by jambonz itself - so without this header every abandoned inbound call looks identical, and SIP;cause=200;text="Call completed elsewhere" is what distinguishes a forked branch losing the race from a caller who hung up.

Two parsing caveats: the header is re-serialized in transit, which normalizes the optional whitespace RFC 3326 allows around ;, so a carrier’s Q.850 ;cause=18 arrives as Q.850;cause=18 - parse tolerantly rather than string-matching. And a message may carry more than one Reason header, in which case they arrive comma-separated; split on commas outside quotes, since a text="..." value may contain one.

sbc_callidstringOptional
the orignal call ID of the call when it arrived at jambonz
originating_sip_ipstringOptional
The IP address that send the call to jambonz
originating_sip_trunk_namestringOptional
The name of the carrier in Jambonz that recieved the call
local_sip_addressstringOptional
Internal Address of the Feature Server handling the call
service_provider_sidstringOptional
The ID of the service provider the account handling the call belongs to
sipobjectOptional
The SIP request for the call
env_varsobjectOptional
Application Environment Variables configured for the applicaiton

Response

Return a 200 containing a JSON payload consisting of an array of verbs