WebhooksEvent Reference

Event Reference

All webhook event types and their payloads.

Payload Structure

Every webhook event follows this structure:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "message.delivered",
  "timestamp": "2026-03-28T10:00:03.000Z",
  "data": {
    "messageId": "msg_xyz",
    "externalMessageId": "external-guid",
    "from": "+19876543210",
    "to": "+14155551234",
    "text": "Hello!",
    "channel": "imessage",
    "metadata": { "customKey": "customValue" },
    "status": "delivered"
  }
}

Message Events

EventDescription
message.queuedMessage accepted and queued for delivery
message.sentMessage sent to the carrier/provider
message.deliveredDelivery confirmed by the recipient’s device
message.readRead receipt received (iMessage only)
message.failedMessage delivery failed
message.fallbackFallback triggered (e.g., iMessage to SMS)
message.inboundInbound message received from a contact

Scheduled Message Events

EventDescription
message.scheduledMessage scheduled for future delivery
message.schedule_cancelledScheduled message was cancelled

Typing Events

EventDescription
typing.indicatorTyping indicator activity detected

Payment Events

EventDescription
payment.request.createdPayment request sent
payment.request.paidPayment detected via incoming message
payment.request.cancelledPayment request cancelled
payment.request.expiredPayment request expired

FaceTime Events

EventDescription
facetime.incomingIncoming FaceTime call detected
facetime.status_changedCall status update (answered, disconnected, etc.)

Inbound Message Payload

{
  "id": "evt_abc123",
  "type": "message.inbound",
  "timestamp": "2026-03-28T10:00:00.000Z",
  "data": {
    "messageId": "msg_xyz789",
    "from": "+14155551234",
    "text": "Hello!",
    "channel": "imessage"
  }
}

Subscribing to Events

Select which events to receive when configuring your webhook:

curl -X PUT https://api.textbubbles.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/textbubbles",
    "events": [
      "message.sent",
      "message.delivered",
      "message.failed",
      "message.inbound",
      "payment.request.paid"
    ]
  }'
ConfigurationInstallation