How do hangup cause fields work in webhooks?

How do hangup cause fields work in webhooks?

Quick Answer: The hangup object in the call.end webhook tells you who disconnected a call and why, using the fields initiated_by, cause and cause_code, which now ship on outgoing calls that were answered at least once.

Overview of the hangup object

hangup sits inside every call.end webhook payload where a call reached an answered state. It describes how the call was terminated and is made up of three fields first introduced as follows:

  • initiated_by – always available since launch
  • cause – new, outgoing calls only
  • cause_code – new, outgoing calls only

Field definitions

The three fields report:

  • initiated_by (string) – UID of the call leg that triggered the disconnect
  • cause (string) – human-readable ISDN hangup cause text
  • cause_code (string) – the matching ISDN Q.850/Q.931 numeric code, sent as a string (e.g. "16")

When is the hangup object present?

  • Answered, then ended – Yes
  • Missed – No
  • Voicemail – No

In short, it will come only when the call was answered at least once before ending on an outgoing leg, and it will not come if the call was missed, routed to voicemail, or never reached an answered state.

Why is cause_code a string?

Although a cause_code is almost always a two-digit number such as "16", sending it as a string guarantees consistent handling across all languages and client systems. Always parse it as a string in your integration instead of forcing a numeric type.

Common cause_code values

  • 16 – Normal clearing (call ended normally)
  • 17 – User busy (called party busy)
  • 18 / 19 – No answer (rang but not answered)
  • 21 – Call rejected (explicitly declined)
  • 27 – Destination out of order (invalid or disconnected number)
  • 28 – Invalid number format
  • 34 – No circuit/channel available (carrier congestion)
  • 38 – Network out of order (carrier network fault)
  • 41 – Temporary failure (often safe to retry)

Full ISDN reference

All values follow the standard ISDN Q.850/Q.931 specification. If you meet a code not listed above, look it up in any public ISDN cause code table for the authoritative meaning.

Need help?

For implementation questions, contact your MyOperator support representative.

Keywords

webhook, hangup, cause_code, cause, initiated_by, ISDN, Q.850, Q.931, call.end, MyOperator