{ "openapi": "3.0.3", "info": { "title": "Notifique API. Webhooks", "description": "Cadastre URLs HTTPS para receber eventos da Notifique em tempo real. Autentique com `Authorization: Bearer sk_live_...` ou `x-api-key`. Escopos: `webhooks:read`, `webhooks:manage`.", "version": "1.0.0" }, "servers": [ { "url": "https://api.notifique.dev", "description": "Produção" } ], "security": [ { "ntfWhBearerAuth": [] }, { "ntfWhApiKeyHeader": [] } ], "tags": [ { "name": "Webhooks", "description": "CRUD de endpoints de webhook do workspace." }, { "name": "Entregas", "description": "Histórico e reenvio de tentativas de entrega de webhook." } ], "paths": { "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Listar webhooks", "description": "Lista webhooks configurados no workspace. Filtre por evento e pagine resultados.", "operationId": "ntfWh_listWebhooks", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Itens por página (máx. 100)." }, { "name": "event", "in": "query", "schema": { "type": "string" }, "description": "Filtra por nome de evento (ex.: `message.sent`)." } ], "responses": { "200": { "description": "Lista paginada de webhooks.", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "clwh_01HABC...", "name": "Meu webhook", "url": "https://api.seudominio.com/receive", "events": [ "message.sent", "message.delivered" ], "instanceIds": [], "enabled": true, "createdAt": "2026-08-01T10:00:00.000Z", "updatedAt": "2026-08-10T12:00:00.000Z", "headers": { "Authorization": "Bearer ********" } } ], "pagination": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 } }, "schema": { "$ref": "#/components/schemas/ntfWh_ListWebhooksResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Criar webhook", "description": "Cadastra uma URL HTTPS que recebe POST JSON quando eventos ocorrem. Guarde o `secret` da resposta para validar `X-Notifique-Signature`. A URL passa por verificação POST (2xx, 401 ou 403 aceitos). Hasta 10 encabezados personalizados; los valores se cifran y se enmascaran en las respuestas GET.", "operationId": "ntfWh_createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfWh_WebhookInput" }, "example": { "name": "Meu webhook", "url": "https://api.seudominio.com/receive", "events": [ "message.sent", "message.delivered", "sms.sent" ], "instanceIds": [], "enabled": true, "headers": { "Authorization": "Bearer teste" } } } } }, "responses": { "200": { "description": "Webhook criado com `secret` (exibido uma vez).", "content": { "application/json": { "example": { "success": true, "data": { "id": "clwh_01HNEW...", "name": "Meu webhook", "url": "https://api.seudominio.com/receive", "events": [ "message.sent", "message.delivered", "sms.sent" ], "instanceIds": [], "enabled": true, "secret": "whsec_shown_once_abc123...", "createdAt": "2026-08-14T20:00:00.000Z", "headers": { "Authorization": "Bearer ********" } } }, "schema": { "$ref": "#/components/schemas/ntfWh_CreateWebhookResponse" } } } }, "400": { "$ref": "#/components/responses/Ntf_BadRequest" }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Consultar webhook", "operationId": "ntfWh_getWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook encontrado (sem `secret`). Hasta 10 encabezados personalizados; los valores se cifran y se enmascaran en las respuestas GET.", "content": { "application/json": { "example": { "success": true, "data": { "id": "clwh_01HABC...", "name": "Meu webhook", "url": "https://api.seudominio.com/receive", "events": [ "message.sent" ], "instanceIds": [], "enabled": true, "headers": { "Authorization": "Bearer ********" } } }, "schema": { "$ref": "#/components/schemas/ntfWh_GetWebhookResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Excluir webhook", "description": "Remove o webhook e cancela entregas futuras. Escopo `webhooks:manage`.", "operationId": "ntfWh_deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook removido.", "content": { "application/json": { "example": { "success": true, "data": { "id": "clwh_01HABC...", "deleted": true } }, "schema": { "$ref": "#/components/schemas/ntfWh_DeleteWebhookResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } }, "put": { "tags": [ "Webhooks" ], "summary": "Atualizar webhook", "description": "Altera URL, eventos, instâncias ou status `enabled`. Escopo `webhooks:manage`. Hasta 10 encabezados personalizados; los valores se cifran y se enmascaran en las respuestas GET.", "operationId": "ntfWh_updateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NtfWh_WebhookInput" }, "example": { "name": "Meu webhook", "url": "https://api.seudominio.com/receive", "events": [ "message.sent", "message.failed" ], "instanceIds": [], "domainIds": [], "pushAppIds": [], "enabled": false, "headers": { "Authorization": "Bearer teste" } } } } }, "responses": { "200": { "description": "Webhook atualizado.", "content": { "application/json": { "example": { "success": true, "data": { "id": "clwh_01HABC...", "enabled": false, "events": [ "message.sent", "message.failed" ], "headers": { "Authorization": "Bearer ********" } } }, "schema": { "$ref": "#/components/schemas/ntfWh_UpdateWebhookResponse" } } } }, "400": { "$ref": "#/components/responses/Ntf_BadRequest" }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Actualizar encabezados/URL", "description": "Actualiza la URL y/o los encabezados personalizados del webhook. Envíe `headers: {}` para eliminarlos todos.", "operationId": "ntfWh_patchWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "headers": { "$ref": "#/components/schemas/NtfWh_WebhookInput/properties/headers" } } }, "example": { "headers": { "Authorization": "Bearer teste" } } } } }, "responses": { "200": { "description": "Webhook actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ntfWh_GetWebhookResponse" } } } }, "400": { "$ref": "#/components/responses/Ntf_BadRequest" }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotacionar secret do webhook", "description": "Gera novo `secret` de assinatura HMAC. O valor anterior invalida imediatamente. O novo secret é retornado **uma vez**. Escopo `webhooks:manage`.", "operationId": "ntfWh_rotateWebhookSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Novo secret emitido.", "content": { "application/json": { "example": { "success": true, "data": { "id": "clwh_01HABC...", "secret": "whsec_new_shown_once_xyz789..." } }, "schema": { "$ref": "#/components/schemas/ntfWh_RotateWebhookSecretResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } } }, "/v1/webhooks/deliveries": { "get": { "tags": [ "Entregas" ], "summary": "Listar entregas", "description": "Histórico de tentativas POST para seus endpoints. Filtre por sucesso, evento, webhook ou messageId.", "operationId": "ntfWh_listDeliveries", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "success", "in": "query", "schema": { "type": "boolean" }, "description": "Filtra entregas bem-sucedidas ou falhas." }, { "name": "event", "in": "query", "schema": { "type": "string" } }, { "name": "webhook_id", "in": "query", "schema": { "type": "string" } }, { "name": "messageId", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Busca livre no payload ou resposta." } ], "responses": { "200": { "description": "Lista paginada de entregas.", "content": { "application/json": { "example": { "success": true, "data": [ { "id": "cldel_01H...", "webhookId": "clwh_01HABC...", "event": "message.sent", "success": true, "httpStatus": 200, "attempts": 1, "messageId": "clmsg_01H...", "createdAt": "2026-08-14T19:55:00.000Z" } ], "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 } }, "schema": { "$ref": "#/components/schemas/ntfWh_ListDeliveriesResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" } } } }, "/v1/webhooks/deliveries/{deliveryId}": { "get": { "tags": [ "Entregas" ], "summary": "Detalhe da entrega", "description": "Payload enviado, resposta HTTP do seu endpoint, tentativas e metadados.", "operationId": "ntfWh_getDelivery", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe completo da entrega.", "content": { "application/json": { "example": { "success": true, "data": { "id": "cldel_01H...", "webhookId": "clwh_01HABC...", "event": "message.sent", "success": false, "httpStatus": 500, "attempts": 2, "payload": { "event": "message.sent", "workspaceId": "clws_..." }, "responseBody": "Internal Server Error", "lastAttemptAt": "2026-08-14T19:56:00.000Z" } }, "schema": { "$ref": "#/components/schemas/ntfWh_GetDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } } }, "/v1/webhooks/deliveries/{deliveryId}/resend": { "post": { "tags": [ "Entregas" ], "summary": "Reenviar entrega", "description": "Recoloca a entrega na fila para nova tentativa POST ao seu endpoint. Escopo `webhooks:manage`.", "operationId": "ntfWh_resendDelivery", "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Entrega reenfileirada.", "content": { "application/json": { "example": { "success": true, "data": { "id": "cldel_01H...", "status": "QUEUED" } }, "schema": { "$ref": "#/components/schemas/ntfWh_ResendDeliveryResponse" } } } }, "401": { "$ref": "#/components/responses/Ntf_Unauthorized" }, "403": { "$ref": "#/components/responses/Ntf_Forbidden" }, "404": { "$ref": "#/components/responses/Ntf_NotFound" } } } } }, "components": { "securitySchemes": { "ntfWhBearerAuth": { "type": "http", "scheme": "bearer", "description": "API key `sk_live_...` ou `sk_test_...`." }, "ntfWhApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternativa ao Bearer." } }, "schemas": { "Ntf_Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string" } }, "example": { "success": false, "error": "string", "message": "string", "code": "string" } }, "NtfWh_WebhookInput": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string", "description": "Nome interno no painel." }, "url": { "type": "string", "format": "uri", "description": "URL HTTPS que recebe POST JSON." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Nomes de evento (ex.: `message.sent`)." }, "instanceIds": { "type": "array", "items": { "type": "string" }, "description": "Filtra por instâncias; vazio = todas." }, "enabled": { "type": "boolean", "default": true }, "domainIds": { "type": "array", "items": { "type": "string" }, "description": "Filtra por domínios de e-mail; vazio = todos." }, "pushAppIds": { "type": "array", "items": { "type": "string" }, "description": "Filtra por apps push; vazio = todos." }, "headers": { "type": "object", "maxProperties": 10, "description": "Encabezados HTTP personalizados opcionales: hasta 10 pares; los nombres deben seguir el formato token HTTP y tener como máximo 128 caracteres; los valores pueden tener hasta 2.048 caracteres y no incluir saltos de línea. Host, Content-Length, Content-Type, Transfer-Encoding, Connection y X-Notifique-* están reservados. Los valores se cifran y se enmascaran en las respuestas GET.", "additionalProperties": { "type": "string", "maxLength": 2048, "pattern": "^[^\\r\\n]*$" }, "example": { "Authorization": "Bearer teste" } } }, "example": { "name": "Exemplo", "url": "https://example.com/resource", "events": [ "string" ], "instanceIds": [ "clxx..." ], "enabled": true, "domainIds": [ "clxx..." ], "pushAppIds": [ "clxx..." ] } }, "NtfBinaryFileResponse": { "type": "string", "format": "binary", "description": "Conteúdo binário (download de arquivo ou mídia)." }, "NtfCsvExportResponse": { "type": "string", "description": "Conteúdo CSV (exportação)." }, "NtfEmptyJsonResponse": { "type": "object", "additionalProperties": false, "description": "Resposta JSON vazia (sucesso sem payload).", "properties": { "success": { "type": "boolean", "example": true } }, "example": { "success": true } }, "ntfWh_ListWebhooksResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "instanceIds": { "type": "array", "items": { "type": "object" } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "headers": { "$ref": "#/components/schemas/ntfWh_WebhookHeaders" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } } }, "example": { "success": true, "data": [ { "id": "clxx...", "name": "Exemplo", "url": "https://example.com/resource", "events": [ "string" ], "instanceIds": [ {} ], "enabled": true, "createdAt": "string", "updatedAt": "string" } ], "pagination": { "total": 1, "page": 1, "limit": 1, "totalPages": 1 } } }, "ntfWh_CreateWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "instanceIds": { "type": "array", "items": { "type": "object" } }, "enabled": { "type": "boolean" }, "secret": { "type": "string" }, "createdAt": { "type": "string" }, "headers": { "$ref": "#/components/schemas/ntfWh_WebhookHeaders" } } } }, "example": { "success": true, "data": { "id": "clxx...", "name": "Exemplo", "url": "https://example.com/resource", "events": [ "string" ], "instanceIds": [ {} ], "enabled": true, "secret": "string", "createdAt": "string", "headers": { "Authorization": "Bearer ********" } } } }, "ntfWh_DeleteWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean" } } } }, "example": { "success": true, "data": { "id": "clxx...", "deleted": true } } }, "ntfWh_GetWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "instanceIds": { "type": "array", "items": { "type": "object" } }, "enabled": { "type": "boolean" }, "headers": { "$ref": "#/components/schemas/ntfWh_WebhookHeaders" } } } }, "example": { "success": true, "data": { "id": "clxx...", "name": "Exemplo", "url": "https://example.com/resource", "events": [ "string" ], "instanceIds": [ {} ], "enabled": true } } }, "ntfWh_UpdateWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" }, "events": { "type": "array", "items": { "type": "string" } }, "headers": { "$ref": "#/components/schemas/ntfWh_WebhookHeaders" } } } }, "example": { "success": true, "data": { "id": "clxx...", "enabled": true, "events": [ "string" ] } } }, "ntfWh_RotateWebhookSecretResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } } } }, "example": { "success": true, "data": { "id": "clxx...", "secret": "string" } } }, "ntfWh_ListDeliveriesResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "webhookId": { "type": "string" }, "event": { "type": "string" }, "success": { "type": "boolean" }, "httpStatus": { "type": "integer" }, "attempts": { "type": "integer" }, "messageId": { "type": "string" }, "createdAt": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "totalPages": { "type": "integer" } } } }, "example": { "success": true, "data": [ { "id": "clxx...", "webhookId": "clxx...", "event": "string", "success": true, "httpStatus": 1, "attempts": 1, "createdAt": "string" } ], "pagination": { "total": 1, "page": 1, "limit": 1, "totalPages": 1 } } }, "ntfWh_GetDeliveryResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "webhookId": { "type": "string" }, "event": { "type": "string" }, "success": { "type": "boolean" }, "httpStatus": { "type": "integer" }, "attempts": { "type": "integer" }, "payload": { "type": "object", "properties": { "event": { "type": "string" }, "workspaceId": { "type": "string" } } }, "responseBody": { "type": "string" }, "lastAttemptAt": { "type": "string" } } } }, "example": { "success": true, "data": { "id": "clxx...", "webhookId": "clxx...", "event": "string", "success": true, "httpStatus": 1, "attempts": 1, "payload": { "event": "string", "workspaceId": "clxx..." }, "responseBody": "string", "lastAttemptAt": "string" } } }, "ntfWh_ResendDeliveryResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } } }, "example": { "success": true, "data": { "id": "clxx...", "status": "string" } } }, "ntfWh_WebhookHeaders": { "type": "object", "description": "Hasta 10 encabezados personalizados; los valores se cifran y se enmascaran en las respuestas GET.", "additionalProperties": { "type": "string" }, "example": { "Authorization": "Bearer ********" } } }, "responses": { "Ntf_Unauthorized": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ntf_Error" }, "example": { "success": false, "error": "Unauthorized", "message": "Invalid API key", "code": "UNAUTHORIZED" } } } }, "Ntf_Forbidden": { "description": "Escopo ausente ou recurso fora da permissão da chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ntf_Error" }, "example": { "success": false, "error": "Forbidden", "message": "Missing scope webhooks:manage", "code": "FORBIDDEN" } } } }, "Ntf_NotFound": { "description": "Recurso não encontrado no workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ntf_Error" }, "example": { "success": false, "error": "Not Found", "message": "Webhook not found", "code": "NOT_FOUND" } } } }, "Ntf_BadRequest": { "description": "Body inválido ou campo inesperado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ntf_Error" }, "examples": { "validation": { "value": { "success": false, "error": "Bad Request", "message": "url must be HTTPS", "code": "VALIDATION_ERROR" } }, "unexpected_fields": { "value": { "success": false, "code": "UNEXPECTED_FIELDS" } } } } } } } } }