Example Webhook Data - v2

Your webhook data doesn’t look like this?This page is for the v2 webhook format, which is used for users registered after November 1st, 2024. For the v1 format, see Example Webhook Data - v1.

Webhook Payload Format

All webhook notifications follow this consistent structure:

{
  "id": "evt_d61aCHRo18",
  "type": "text.incoming.sms", 
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    // event-specific data
  }
}

Events

Below are the events that Contiguity can send to your webhook endpoint. Use the type field to determine which event occurred.

`text.incoming.sms`

An incoming SMS message was received.

{
  "id": "evt_d61aCHRo18",
  "type": "text.incoming.sms",
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Hello world",
    "timestamp": 1726502400
  }
}

`text.incoming.mms`

An incoming MMS message with attachments was received.

{
  "id": "evt_d61aCHRo18",
  "type": "text.incoming.mms",
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "from": "+15551234567",
    "to": "+15559876543", 
    "body": "Check out this image!",
    "timestamp": 1726502400,
    "attachments": [
      {
        "url": "https://api.contiguity.com/attachments/15551234567/15559876543/image.jpg",
        "mime": "image/jpeg",
        "filename": "image.jpg"
      }
    ]
  }
}

`text.delivery.confirmed`

SMS/MMS delivery was confirmed by the carrier.

{
  "id": "evt_d61aCHRo18",
  "type": "text.delivery.confirmed",
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "from": "+15551234567",
    "to": "+15559876543",
    "message_id": "msg_abc123",
    "timestamp": 1726502400
  }
}

`text.delivery.failed`

SMS/MMS delivery failed or timed out.

{
  "id": "evt_d61aCHRo18",
  "type": "text.delivery.failed",
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "from": "+15551234567",
    "to": "+15559876543",
    "message_id": "msg_abc123",
    "timestamp": 1726502400,
    "error": "Carrier never provided delivery confirmation. Your message may have delivered, but Contiguity has no idea if it did."
  }
}

`text.cancelled` / `imessage.cancelled` / `whatsapp.cancelled`

Fired when you cancel a queued send (POST /conversations/cancel/{msg_id}). Does not mean the message was unsent — an in-flight send may still go out.

{
  "id": "evt_d61aCHRo18",
  "type": "text.cancelled",
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "from": "+15551234567",
    "to": "+15559876543",
    "message_id": "text_abc123",
    "timestamp": 1726502400
  }
}

`imessage.incoming`

An incoming iMessage was received.

{
  "id": "evt_d61aCHRo18",
  "type": "imessage.incoming",
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "from": "+15551234567",
    "to": "+15559876543",
    "body": "Hello from iMessage",
    "timestamp": 1726502400,
    "attachments": []
  }
}

`numbers.substitution`

When the requested number is unavailable, a random number is used instead.

{
  "id": "evt_d61aCHRo18",
  "type": "numbers.substitution", 
  "timestamp": 1726502400,
  "api_version": "v2025.9.7",
  "data": {
    "original_number": "+15551111111",
    "used_number": "+15552222222",
    "reason": "requested_unavailable_random_used",
    "message_id": "msg_abc123",
    "timestamp": 1726502400
  }
}

`otp.reverse.verified`

A user has verified their phone number using a Reverse OTP.

{
  "id": "evt_dgUIkRo18",
  "type": "otp.reverse.verified",
  "timestamp": 1726502400,
  "api_version": "v2026.8.20",
  "data": {
    "otp_id": "r_otp_123456",
    "number": "+15551234567",
    "to": "+16465550123",
    "service": "sms",
    "factor": "ABC123",
    "status": "verified",
    "expires_at": "2026-08-20T19:30:00.000Z",
    "verified_at": "2026-08-20T19:15:00.000Z"
  }
}

`email.incoming`

An incoming email was received.

{
  "id": "evt_d61aCHRo18",
  "type": "email.incoming",
  "timestamp": 1726502400,
  "api_version": "v2025.12.7",
  "data": {
    "email_id": "in_email_xxx",
    "from": { "name": "Sender", "address": "sender@example.com", "complete": "Sender <sender@example.com>" },
    "to": { "name": null, "address": "user@example.com", "complete": "<user@example.com>" },
    "cc": [],
    "bcc": [],
    "reply_to": null,
    "subject": "Hello",
    "body": {
      "text": "Hello world",
      "html": "<p>Hello world</p>",
      "raw": "raw MIME email"
    },
    "timestamp": 1726502400,
    "headers": {
      "return-path": [
        { "address": "sender@example.com", "name": "" }
      ]
    },
    "in_reply_to": "<msg_prior@example.com>",
    "references": ["<msg_prior@example.com>"],
    "attachments": [
      {
        "id": "att_abc",
        "filename": "file.png",
        "content_type": "image/png",
        "size": 12345,
        "url": "https://api.contiguity.com/attachments/email/in_email_xxx/file.png"
      }
    ]
  }
}

`facetime.call.initiated`

An outbound FaceTime Audio dial created the call. data.status is queued. Posted to your facetime webhook URL, else catchall. data is the same call object as Get a call.

{
  "id": "evt_d61aCHRo18",
  "type": "facetime.call.initiated",
  "timestamp": 1758998599994,
  "api_version": "v2026.9.27",
  "data": {
    "call_id": "call_ftaAbCdEfGhIjKlMnOp",
    "ft_audio_line": "+15551234567",
    "to": "+15559876543",
    "from": "+15551234567",
    "caller_id": "+1 (555) 123-4567",
    "direction": "outbound",
    "status": "queued",
    "cause": null,
    "link": null,
    "webrtc": {
      "url": "wss://rtc.contiguity.cloud",
      "room": "contiguity:facetime:call_ftaAbCdEfGhIjKlMnOp",
      "token": "eyJhbGciOi...",
      "join": "https://facetime.contiguity.com/call?j=example"
    },
    "participants": [],
    "created_at": "2026-09-27T19:23:19.994Z",
    "answered_at": null,
    "ended_at": null,
    "duration": null
  }
}

`facetime.call.ringing`

The outbound call is ringing, or an inbound call arrived. data.status is ringing. Same envelope and call object as initiated: link is still null, participants is [], webrtc is present, duration is null.

`facetime.call.answered`

The call is connected. data.status is in_progress. link is now the FaceTime join URL. participants is the remote party.

{
  "id": "evt_d61aCHRo18",
  "type": "facetime.call.answered",
  "timestamp": 1758998615578,
  "api_version": "v2026.9.27",
  "data": {
    "call_id": "call_ftaAbCdEfGhIjKlMnOp",
    "ft_audio_line": "+15551234567",
    "to": "+15559876543",
    "from": "+15551234567",
    "caller_id": "+1 (555) 123-4567",
    "direction": "outbound",
    "status": "in_progress",
    "cause": null,
    "link": "https://facetime.apple.com/join#v=1&p=example&k=example",
    "webrtc": {
      "url": "wss://rtc.contiguity.cloud",
      "room": "contiguity:facetime:call_ftaAbCdEfGhIjKlMnOp",
      "token": "eyJhbGciOi...",
      "join": "https://facetime.contiguity.com/call?j=example"
    },
    "participants": ["+15559876543"],
    "created_at": "2026-09-27T19:23:19.994Z",
    "answered_at": "2026-09-27T19:23:35.578Z",
    "ended_at": null,
    "duration": null
  }
}

`facetime.call.rejected`

You rejected an inbound ringing call via POST /{call_id}/reject. Same call object; status reflects the rejected call.

`facetime.call.failed`

Contiguity could not place the call. data.status is failed.

`facetime.call.ended`

The call ended: you hung up, the recipient hung up, or FaceTime disconnected. data.status is completed. webrtc is null. duration is seconds of connected time. participants at hangup is the remaining roster, not everyone who was on the call. If the recipient already left, this is often just your FaceTime Audio line.

{
  "id": "evt_d61aCHRo18",
  "type": "facetime.call.ended",
  "timestamp": 1758998689511,
  "api_version": "v2026.9.27",
  "data": {
    "call_id": "call_ftaAbCdEfGhIjKlMnOp",
    "ft_audio_line": "+15551234567",
    "to": "+15559876543",
    "from": "+15551234567",
    "caller_id": "+1 (555) 123-4567",
    "direction": "outbound",
    "status": "completed",
    "cause": null,
    "link": "https://facetime.apple.com/join#v=1&p=example&k=example",
    "webrtc": null,
    "participants": ["+15551234567"],
    "created_at": "2026-09-27T19:23:19.994Z",
    "answered_at": "2026-09-27T19:23:35.578Z",
    "ended_at": "2026-09-27T19:24:49.511Z",
    "duration": 74
  }
}

Event	`participants`
initiated / ringing	`[]`
answered	Remote party, e.g. `["+15559876543", "your_number"]`
ended	Remaining handles after hangup. If the recipient already left, this is often just your FaceTime Audio line.

`identity.verification_session.started`

A user began verifying their identity.

`identity.verification_session.processing`

A user has submitted their identity information, and Contiguity is verifying it.

`identity.verification_session.verified`

A user has submitted their identity information, and the verification is complete. Here, you will also receive a data.verification_report field, which contains the Verification Report ID for you to fetch.

`identity.verification_session.failed`

A user has submitted their identity information, but Contiguity believes their information is invalid (high-accuracy)

`identity.verification_session.requires_input`

A user has submitted their identity information, but Contiguity isn’t sure of their identity. You will have to review their information in the Console, and manually approve or deny them.

`identity.verification_session.manually_approved`

A user’s verification session was manually approved by you in the Console.

`identity.verification_session.manually_denied`

A user’s verification session was manually denied by you in the Console.

`identity.verification_report.generated`

In addition to identity.verification_session.completed, you will also receive this event. Here, there will be non-sensitive information about the verification report, such as age & country of residence.

Getting Started

Text

Email

OTP

iMessage

FaceTime

Lease

Number Intelligence

Entitlements

Identity

WhatsApp

Example Webhook Data - v2

Webhook Payload Format

Events

`text.incoming.sms`

`text.incoming.mms`

`text.delivery.confirmed`

`text.delivery.failed`

`text.cancelled` / `imessage.cancelled` / `whatsapp.cancelled`

`imessage.incoming`

`numbers.substitution`

`otp.reverse.verified`

`email.incoming`

`facetime.call.initiated`

`facetime.call.ringing`

`facetime.call.answered`

`facetime.call.rejected`

`facetime.call.failed`

`facetime.call.ended`

`identity.verification_session.started`

`identity.verification_session.processing`

`identity.verification_session.verified`

`identity.verification_session.failed`

`identity.verification_session.requires_input`

`identity.verification_session.manually_approved`

`identity.verification_session.manually_denied`

`identity.verification_report.generated`

​Webhook Payload Format

​Events

​text.incoming.sms

​text.incoming.mms

​text.delivery.confirmed

​text.delivery.failed

​text.cancelled / imessage.cancelled / whatsapp.cancelled

​imessage.incoming

​numbers.substitution

​otp.reverse.verified

​email.incoming

​facetime.call.initiated

​facetime.call.ringing

​facetime.call.answered

​facetime.call.rejected

​facetime.call.failed

​facetime.call.ended

​identity.verification_session.started

​identity.verification_session.processing

​identity.verification_session.verified

​identity.verification_session.failed

​identity.verification_session.requires_input

​identity.verification_session.manually_approved

​identity.verification_session.manually_denied

​identity.verification_report.generated

Webhook Payload Format

Events

`text.incoming.sms`

`text.incoming.mms`

`text.delivery.confirmed`

`text.delivery.failed`

`text.cancelled` / `imessage.cancelled` / `whatsapp.cancelled`

`imessage.incoming`

`numbers.substitution`

`otp.reverse.verified`

`email.incoming`

`facetime.call.initiated`

`facetime.call.ringing`

`facetime.call.answered`

`facetime.call.rejected`

`facetime.call.failed`

`facetime.call.ended`

`identity.verification_session.started`

`identity.verification_session.processing`

`identity.verification_session.verified`

`identity.verification_session.failed`

`identity.verification_session.requires_input`

`identity.verification_session.manually_approved`

`identity.verification_session.manually_denied`

`identity.verification_report.generated`