> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capitalcheckin.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Entrega, firma y versión del payload de los webhooks de Capital Check In

Los webhooks notifican a una URL tuya cuando ocurre un evento de la empresa. El catálogo de eventos y los JSON de ejemplo están en [Eventos](/integrations/webhooks/events).

**Esquema del payload: `1.0.0`** (2 de octubre de 2026).

## Cómo se versiona

El cuerpo HTTP no trae un campo de versión. La versión vive en esta documentación.

| Cambio | Versión |
| - | - |
| Se agrega un campo | Menor (`1.1.0`) |
| Se quita o se renombra un campo, o cambia el significado | Mayor (`2.0.0`) |

Cada cambio se anota en la tabla de versiones del [catálogo](/integrations/webhooks/events) y en el changelog. El esquema `1.0.0` describe lo que envía `SendWebhookJob` hoy.

## Sobre

```json theme={null}
{
  "event": "collaborator.created",
  "timestamp": "2026-10-02T15:30:00.000000Z",
  "data": {
    "event_type": "App\\Events\\CollaboratorAdded",
    "timestamp": "2026-10-02T15:30:00.000000Z",
    "data": {}
  }
}
```

| Campo | Tipo | Descripción |
| - | - | - |
| `event` | string | Nombre suscrito, por ejemplo `collaborator.created` |
| `timestamp` | string | Fecha ISO 8601 de la entrega |
| `data.event_type` | string | Clase PHP que disparó el listener |
| `data.timestamp` | string | Fecha ISO 8601 en que se armó el payload |
| `data.data` | object | Recurso del evento. No viene en todos los eventos |
| `data.idempotency_key` | string | Solo en `report.created`. También viaja en `X-Webhook-Idempotency-Key` |

`GET /v1/webhooks/perform-list` devuelve datos de muestra para Zapier. Esa forma es plana y no es el cuerpo que recibe tu URL.

## Headers

| Header | Valor |
| - | - |
| `Content-Type` | `application/json` |
| `User-Agent` | `Laravel-Webhook/1.0` |
| `X-Webhook-Event` | Nombre del evento |
| `X-Webhook-Signature` | HMAC-SHA256 en hexadecimal |
| `X-Webhook-Timestamp` | Unix time de la entrega |
| `X-Webhook-Idempotency-Key` | Solo si el payload trae `idempotency_key` |

Los headers que guardaste en la suscripción se agregan después y pueden reemplazar uno de estos.

## Firma

La firma es HMAC-SHA256 del JSON `{ "event", "timestamp", "data" }` con el secret de la suscripción. Compara con `hash_equals` (o el equivalente de tiempo constante en tu lenguaje).

El job firma una copia codificada aparte del cuerpo que envía el cliente HTTP. Si la verificación contra los bytes crudos falla, revisa el orden de llaves y el escapado JSON antes de descartar la petición: las dos marcas de tiempo se generan por separado y pueden no coincidir.

## Entrega

* Timeout de 30 segundos. La respuesta esperada es `2xx`.
* `410` desactiva la suscripción.
* `4xx` (excepto `410`) reintenta hasta 3 veces con backoff exponencial desde 60 segundos y luego desactiva.
* `5xx` y errores de red reintentan hasta 5 veces y luego desactivan.
* Puedes suscribirte a un evento (`collaborator.created`), a un namespace (`collaborator.*`) o a todos (`*`).

## Eventos declarados que no se envían

El enum acepta estos nombres, pero ningún listener los dispara:

* `device.updated`
* `geofence.updated`
* `schedule.deleted`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.