Webhooks

Configura tus webhooks para recibir en tiempo real los eventos que te interesan. Cada vez que ocurre algo relevante —un trámite cambia de estado, se genera un documento, aparece una incidencia— Punto envía una petición POST a la URL que hayas configurado.

Cómo funciona

Cuando ocurre un evento, Punto realiza una petición POST a tu endpoint con un cuerpo JSON. El campo event identifica qué ha ocurrido y el campo data contiene los detalles del recurso afectado.

Todos los eventos comparten tres campos comunes: id (identificador del recurso), path (ruta para obtener el detalle completo) y timestamp (fecha y hora en ISO 8601). Cada tipo de evento añade campos específicos del recurso que permiten enrutar tu lógica sin necesidad de hacer una llamada adicional.

Tu endpoint debe responder con HTTP 200 en menos de 5 segundos. Si no, Punto reintentará el envío.

Suscribirte a eventos

Suscripción a eventos concretos

POST

{
  "url": "https://tu-servidor.com/webhooks/punto",
  "events": ["procedure.status_changed", "procedure.finished"]
}

Suscripción a todos los eventos

Usa "*" como selector para recibir todos los eventos disponibles, incluidos los que se añadan en el futuro. Así no tendrás que actualizar tu suscripción cuando lancemos nuevos tipos de evento.

POST

{
  "url": "https://tu-servidor.com/webhooks/punto",
  "events": ["*"]
}

Varias URLs para distintos eventos

Puedes crear múltiples suscripciones y apuntar cada una a una URL diferente:

POST

{
  "url": "https://tu-servidor.com/webhooks/tramites",
  "events": ["procedure.status_changed", "procedure.finished", "procedure.document.added"]
}

POST

{
  "url": "https://tu-servidor.com/webhooks/incidencias",
  "events": ["procedure.incident.added", "procedure.incident.solved"]
}

Gestionar tus suscripciones

GET

// Listar suscripciones activas

DELETE

// Eliminar una suscripción

Staging y producción

Los webhooks se configuran de forma independiente por entorno. Una suscripción creada en desarrollo no existe en producción y viceversa.

Entorno	URL base
Desarrollo	`https://api.dev.punto.ai`
Producción	`https://api.punto.ai`

Crea tus suscripciones en cada entorno por separado, usando la clave de API correspondiente a cada uno.

Recibir y procesar eventos

Tu endpoint recibirá una petición POST con el siguiente formato:

procedure.status_changed

{
  "event": "procedure.status_changed",
  "data": {
    "id": "pro_1234",
    "path": "/v1/procedures/pro_1234",
    "procedureType": "VEHICLE_REGISTRATION",
    "status": "IN_PROGRESS",
    "timestamp": "2025-08-12T10:30:00.000Z"
  }
}

Cuando necesites el detalle completo del recurso, usa el campo path del payload para hacer un GET:

GET

// Sustituye {id} por el valor de data.path recibido en el evento

Eventos disponibles

Trámites

Evento	Cuándo se emite
`procedure.status_changed`	Un trámite ha cambiado de estado
`procedure.finished`	Un trámite ha llegado a un estado terminal (completado o fallido)
`procedure.document.added`	Se ha generado un nuevo documento en el trámite
`procedure.incident.added`	Se ha registrado una incidencia en el trámite
`procedure.incident.solved`	Una incidencia ha sido marcada como resuelta
`procedure.incident.removed`	Una incidencia ha sido eliminada

Certificados de ahorro energético

Evento	Cuándo se emite
`energy_saving_certificate.status_changed`	Un certificado ha cambiado de estado
`energy_saving_certificate.document.added`	Se ha generado un nuevo documento en el certificado

Firmas electrónicas

Evento	Cuándo se emite
`signature.status_changed`	El estado de una solicitud de firma ha cambiado

Consulta la Referencia API para el payload completo de cada evento y el esquema de suscripción.

Siguientes pasos

Trámites — cómo crear y seguir trámites con la DGT
Referencia API — documentación completa de todos los endpoints