> For the complete documentation index, see [llms.txt](https://prometheo.gitbook.io/prometheo-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://prometheo.gitbook.io/prometheo-api/webhooks.md).

# Webhooks

## Suscribirse a un evento de webhook

> Suscríbete para recibir notificaciones webhook. Existen dos tipos de eventos:\
> \
> \*\*Eventos de mensajes\*\* (message.incoming, message.outgoing): Requieren connection\_type. Se envían cuando hay mensajes entrantes o salientes en un canal específico.\
> \
> \*\*Eventos de leads\*\* (lead.created, lead.updated, lead.smart\_tag\_assigned, lead.variable\_assigned): NO requieren connection\_type. Se envían cuando se crea un lead, cuando cambia un dato público del contacto (perfil, etiquetas, variables, moderador, comentarios o anuncios), cuando se asigna un smart tag o cuando se modifica una variable.\
> \
> \*\*Seguridad\*\*: Todos los webhooks incluyen un header X-Webhook-Signature con firma HMAC-SHA256. Calcula HMAC-SHA256(request\_body, tu\_api\_key) y compara con el header para verificar autenticidad.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"WebhookSubscriptionRequest":{"type":"object","required":["event_type","webhook_url"],"properties":{"connection_type":{"type":"string","description":"Requerido solo para eventos de mensajes (message.incoming, message.outgoing). No se requiere para eventos de leads.","enum":["whatsapp-business","instagram","facebook","whatsapp-lite","whatsapp-hybrid","email","tiktok","mercado-libre"]},"event_type":{"type":"string","description":"Tipo de evento. Eventos de mensajes requieren connection_type, eventos de leads no requieren connection_type.","enum":["message.incoming","message.outgoing","lead.created","lead.updated","lead.smart_tag_assigned","lead.variable_assigned"]},"webhook_url":{"type":"string","format":"uri"}}},"WebhookSubscriptionResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"subscription":{"type":"object","properties":{"id":{"type":"string","description":"ID único de la suscripción"},"connection_type":{"type":"string","description":"Tipo de conexión"},"event_type":{"type":"string","description":"Tipo de evento"},"webhook_url":{"type":"string","description":"URL del webhook"},"active":{"type":"boolean","description":"Estado activo de la suscripción"},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"}}}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/webhooks/subscription":{"post":{"tags":["Webhooks"],"summary":"Suscribirse a un evento de webhook","description":"Suscríbete para recibir notificaciones webhook. Existen dos tipos de eventos:\n\n**Eventos de mensajes** (message.incoming, message.outgoing): Requieren connection_type. Se envían cuando hay mensajes entrantes o salientes en un canal específico.\n\n**Eventos de leads** (lead.created, lead.updated, lead.smart_tag_assigned, lead.variable_assigned): NO requieren connection_type. Se envían cuando se crea un lead, cuando cambia un dato público del contacto (perfil, etiquetas, variables, moderador, comentarios o anuncios), cuando se asigna un smart tag o cuando se modifica una variable.\n\n**Seguridad**: Todos los webhooks incluyen un header X-Webhook-Signature con firma HMAC-SHA256. Calcula HMAC-SHA256(request_body, tu_api_key) y compara con el header para verificar autenticidad.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionRequest"}}}},"responses":{"200":{"description":"Suscripción creada exitosamente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionResponse"}}}},"400":{"description":"Error de validación o conexión no encontrada/no habilitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"No autorizado (API Key ausente o inválida)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Desuscribirse de un evento de webhook

> Elimina una suscripción de webhook. Para eventos de mensajes se requiere connection\_type, para eventos de leads solo se requiere event\_type.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/webhooks/subscription":{"delete":{"tags":["Webhooks"],"summary":"Desuscribirse de un evento de webhook","description":"Elimina una suscripción de webhook. Para eventos de mensajes se requiere connection_type, para eventos de leads solo se requiere event_type.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_type"],"properties":{"connection_type":{"type":"string","description":"Requerido solo para eventos de mensajes","enum":["whatsapp-business","instagram","facebook","whatsapp-lite","whatsapp-hybrid","email","tiktok","mercado-libre"]},"event_type":{"type":"string","enum":["message.incoming","message.outgoing","lead.created","lead.updated","lead.smart_tag_assigned","lead.variable_assigned"]}}}}}},"responses":{"200":{"description":"Suscripción eliminada exitosamente","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Suscripción no encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```

## Listar todas las suscripciones de webhook

> Obtiene todas las suscripciones de webhook activas para tu organización, con filtrado opcional.

```json
{"openapi":"3.0.3","info":{"title":"Prometheo External API","version":"1.0.0"},"tags":[{"name":"Webhooks"}],"servers":[{"url":"https://api.prometheo.ai/public/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}},"schemas":{"WebhookSubscriptionInfo":{"type":"object","properties":{"id":{"type":"string","description":"ID único de la suscripción"},"connection_type":{"type":"string","description":"Tipo de conexión"},"event_type":{"type":"string","description":"Tipo de evento"},"webhook_url":{"type":"string","description":"URL del webhook"},"active":{"type":"boolean","description":"Estado activo de la suscripción"},"connection_enabled":{"type":"boolean","description":"Si la conexión está actualmente habilitada para la organización"},"connection_status":{"type":"string","description":"Estado de la conexión"},"created_at":{"type":"string","format":"date-time","description":"Fecha de creación"},"updated_at":{"type":"string","format":"date-time","description":"Fecha de última actualización"}}},"ApiError":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"}}}}},"paths":{"/webhooks/subscriptions":{"get":{"tags":["Webhooks"],"summary":"Listar todas las suscripciones de webhook","description":"Obtiene todas las suscripciones de webhook activas para tu organización, con filtrado opcional.","parameters":[{"name":"connection_type","in":"query","required":false,"description":"Filtrar por tipo de conexión (solo aplica a eventos de mensajes)","schema":{"type":"string","enum":["whatsapp-business","instagram","facebook","whatsapp-lite","whatsapp-hybrid","email","tiktok","mercado-libre"]}},{"name":"event_type","in":"query","required":false,"description":"Filtrar por tipo de evento","schema":{"type":"string","enum":["message.incoming","message.outgoing","lead.created","lead.updated","lead.smart_tag_assigned","lead.variable_assigned"]}}],"responses":{"200":{"description":"Suscripciones obtenidas exitosamente","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscriptionInfo"}},"count":{"type":"integer"}}}}}},"401":{"description":"No autorizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Error interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}
```