Eventos de Webhook

El sobre del evento

Cada entrega de webhook es un POST HTTP con un cuerpo JSON. Todos los eventos comparten el mismo sobre de nivel superior:

{
  "id": "evt_9f2c4b7a1d3e5f60718293a4b5c6d7e8",   // idempotency key
  "type": "order.approved",                        // event name
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": {
    "uid": "abc123",
    "companyName": "Acme Home Services"
  },
  "data": { /* resource snapshot — see below */ },
  "changes": {                                     // only on *.approved, *.completed,
    "previous": { "status": "new" },               // *.status_changed, *.rescheduled
    "current": { "status": "approved" }
  }
}

Cada entrega también lleva el nombre del evento en el encabezado de solicitud webhook-event, junto con los encabezados de firma (webhook-id, webhook-timestamp, webhook-signature) descritos en la guía de Webhooks.

Índice de eventos

Los valores de estado en los payloads son los valores almacenados sin procesar (draft, new, read, approved, complete, archived) — consulta Estados de Órdenes.

Eventos de orden — payload de data

order.created, order.approved, order.completed, order.rescheduled y order.status_changed envían todos la misma instantánea de Order en data:

{
  "id": "req_abc123",                              // order ID
  "status": "approved",                            // see Order Statuses reference
  "appointmentDateTime": "2026-08-01T13:00:00.000Z",
  "inspectionType": "Buyer Inspection",            // your service category name
  "streetAddress": "123 Main St",
  "city": "Springfield",
  "region": "IL",
  "postalCode": "62701",
  "country": "US",
  "timezone": "America/Chicago",
  "contactName": "Jane Buyer",
  "contactEmail": "jane@example.com",
  "contactPhone": "(555) 123-4567",
  "contactType": "client",
  "totalPrice": 450,
  "totalTime": 120,                                // duration in minutes
  "paid": false,
  "agreementSigned": true,
  "assignedInspectors": ["uid1", "uid2"],          // assigned team member IDs
  "requestDateTime": "2026-07-20T09:15:00.000Z",   // when the order was created
  "approvedDateTime": "2026-07-21T10:00:00.000Z",
  "completedDateTime": "2026-08-01T16:30:00.000Z"
}

Los campos de fecha son cadenas ISO 8601. Cualquier campo sin valor se omite del payload en lugar de enviarse como null.

changes por evento de orden

• order.approved — changes.previous.status / changes.current.status (current siempre es "approved")
• order.completed — changes.previous.status / changes.current.status (current siempre es "complete")
• order.status_changed — changes.previous.status / changes.current.status
• order.rescheduled — changes.previous.appointmentDateTime / changes.current.appointmentDateTime (cadenas ISO 8601)
• order.created — sin campo changes

invoice.paid — payload de data

Se dispara la primera vez que el indicador paid de una Order se vuelve true. El payload de data es la misma instantánea de Order mostrada arriba — no un objeto de factura. No hay campos específicos de factura (sin número de factura, monto pagado o método de pago); usa totalPrice y el indicador paid: true, o consulta los detalles de la factura desde la API. No se envía ningún campo changes.

report.published — payload de data

Se dispara cuando una Order se vuelve por primera vez tanto pagada como con acuerdo firmado — el momento en que su Report publicado se libera al cliente. El payload de data es la instantánea de Order mostrada arriba, más un campo adicional:

{
  "orderId": "req_abc123",   // same as data.id — the order this report belongs to
  "id": "req_abc123",
  "status": "complete"
  // …all other order snapshot fields
}

No se envía ningún campo changes. El payload no incluye URLs de informe.

Eventos a los que puedes suscribirte pero que aún no se disparan

El editor de endpoints también lista order.updated, invoice.created, contact.created y contact.updated. Estos nombres de evento están reservados y se pueden seleccionar, pero ninguna actividad de cuenta actual los produce — los endpoints suscritos solo a estos eventos no recibirán entregas. Si se emiten en el futuro usarán el sobre estándar; sus campos data todavía no están definidos.

Eventos de prueba — webhook.test

Hacer clic en Probar en un endpoint envía un evento webhook.test:

{
  "id": "evt_test_5f0e…",        // prefixed evt_test_
  "type": "webhook.test",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": { "uid": "abc123" },
  "data": {
    "message": "This is a test webhook event.",
    "timestamp": "2026-07-28T14:30:00.000Z"
  }
}

Los eventos de prueba no están firmados — llevan un encabezado X-Webhook-Test: true en lugar de los encabezados de firma. Tu receptor debería aceptarlos sin verificación de firma (o reconocer el encabezado y omitir la verificación solo para las pruebas).

Responder a las entregas

• Responde con cualquier estado 2xx dentro de 10 segundos para confirmar una entrega.
• Las respuestas 5xx y los tiempos de espera se tratan como temporales — la entrega se reintenta.
• Otras respuestas 4xx se tratan como permanentes — esa entrega no se reintenta.
• Responder 410 Gone le dice a ITB que deje de enviar: el endpoint se deshabilita de inmediato.

Los límites de endpoint, la deshabilitación automática tras fallos repetidos, el historial de entregas y la verificación de firma se explican en la guía de Webhooks.

Relacionado

• Webhooks — configura endpoints, secretos e historial de entregas
• Conectar Aplicaciones a la API — claves de API y aplicaciones OAuth como Zapier
• Integraciones — todo en la pestaña de Integraciones
• Estados de Órdenes — los valores de estado que aparecen en los payloads