> ## Documentation Index > Fetch the complete documentation index at: https://docs.zeriqpay.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar endpoint de webhook > Cadastra uma URL HTTPS para receber eventos Cadastre o destino das notificações. A API gera um segredo único e o retorna uma única vez. ## Autenticação Todas as rotas exigem uma API Key no header `X-API-Key`. A chave deve começar com `zeriq_`. ```http theme={null} X-API-Key: zeriq_sua_chave ``` ```bash cURL theme={null} curl -X POST "https://api.zeriqpay.com.br/v1/webhooks/create" \ -H "X-API-Key: zeriq_sua_chave" \ -H "Content-Type: application/json" \ -d '{"name":"Pagamentos","url":"https://app.exemplo.com/webhooks/zeriqpay","events":["payment.paid","payment.failed"]}' ``` ### Body * `name` (opcional): nome entre 1 e 120 caracteres. * `url` (obrigatório): URL HTTPS que receberá os eventos. * `events` (obrigatório): lista única com pelo menos um evento suportado. ## Referência * **Método:** `POST` * **Rota:** `/v1/webhooks/create` * **Escopo:** `webhooks.create` * **Resposta de sucesso:** `201 Created` O campo `secret` começa com `whsec_` e não aparece novamente em consultas futuras. Armazene-o em um secret manager. ### Exemplo de resposta ```json theme={null} {"success":true,"message":"Endpoint de webhook criado com sucesso. Guarde o segredo, ele não será exibido novamente.","data":{"id":"cmid_webhook","name":"Pagamentos","url":"https://app.exemplo.com/webhooks/zeriqpay","events":["payment.paid","payment.failed"],"active":true,"secret":"whsec_exemplo"}} ``` ### Erros comuns * `400`: URL, eventos ou body inválidos. * `401`: API Key ausente ou inválida. * `403`: a chave não possui o escopo `webhooks.create`. * `404`: endpoint não encontrado ou não pertence à conta. ## OpenAPI ````yaml POST /v1/webhooks/create openapi: 3.1.0 info: title: ZeriqPay API description: >- Referência da API v1 da ZeriqPay. As rotas de gerenciamento de webhooks não fazem parte desta documentação. version: 1.0.0 contact: name: ZeriqPay url: https://api.zeriqpay.com.br servers: - url: https://api.zeriqpay.com.br description: Produção security: - apiKeyAuth: [] tags: - name: Conta description: Dados, taxas e limites da conta - name: Pagamentos PIX description: Cobranças PIX - name: Transações description: Consulta de transações - name: Transferências description: Saídas PIX, cripto e internas - name: Reembolsos description: Reembolsos de cobranças - name: Disputas MED description: Consulta e envio de evidências MED - name: Webhooks description: Cadastro e configuração dos endpoints de webhook paths: /v1/webhooks/create: post: tags: - Webhooks summary: Criar endpoint de webhook description: >- Cadastra uma URL HTTPS e os eventos que devem ser enviados para ela. O `secret` só é retornado nesta resposta; armazene-o imediatamente. **Escopo necessário:** `webhooks.create`. operationId: createWebhookEndpoint requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookRequest' examples: default: summary: Criar endpoint value: name: Pagamentos url: https://app.exemplo.com/webhooks/zeriqpay events: - payment.paid - payment.failed responses: '201': description: Endpoint criado. O segredo é retornado somente nesta resposta. content: application/json: schema: $ref: '#/components/schemas/CreateWebhookResponse' example: success: true message: >- Endpoint de webhook criado com sucesso. Guarde o segredo, ele não será exibido novamente. data: id: cmid_webhook name: Pagamentos url: https://app.exemplo.com/webhooks/zeriqpay events: - payment.paid - payment.failed active: true lastDeliveryAt: null createdAt: '2026-10-28T12:00:00.000Z' updatedAt: '2026-10-28T12:00:00.000Z' secret: whsec_exemplo '400': description: Corpo ou parâmetros inválidos. content: application/json: schema: $ref: '#/components/schemas/GenericResponse' example: success: false message: Dados inválidos. '401': description: API Key ausente ou inválida content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '403': description: Conta bloqueada ou escopo insuficiente content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '404': description: Webhook não encontrado content: application/json: schema: $ref: '#/components/schemas/GenericResponse' '429': description: Limite específico da rota excedido content: application/json: schema: $ref: '#/components/schemas/GenericResponse' security: - apiKeyAuth: [] components: schemas: CreateWebhookRequest: type: object required: - url - events properties: name: type: string minLength: 1 maxLength: 120 url: type: string format: uri pattern: ^https:// maxLength: 2048 events: type: array minItems: 1 uniqueItems: true items: type: string enum: - payment.created - payment.paid - payment.failed - payment.pix.expired - refund.requested - refund.completed - refund.failed - transfer.created - transfer.completed - transfer.failed - transfer.internal.completed - transfer.internal.received - med.created - med.evidence_sent - med.updated - webhook.test CreateWebhookResponse: type: object required: - success - message - data properties: success: type: boolean example: true message: type: string data: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: - secret properties: secret: type: string example: whsec_xxx GenericResponse: type: object properties: success: type: boolean message: type: string data: type: object additionalProperties: true required: - success WebhookEndpoint: type: object required: - id - url - events - active - createdAt - updatedAt properties: id: type: string example: cmid_webhook name: type: - string - 'null' example: Pagamentos url: type: string format: uri example: https://app.exemplo.com/webhooks/zeriqpay events: type: array items: type: string enum: - payment.created - payment.paid - payment.failed - payment.pix.expired - refund.requested - refund.completed - refund.failed - transfer.created - transfer.completed - transfer.failed - transfer.internal.completed - transfer.internal.received - med.created - med.evidence_sent - med.updated - webhook.test example: - payment.paid - payment.failed active: type: boolean example: true lastDeliveryAt: type: - string - 'null' format: date-time example: null createdAt: type: string format: date-time updatedAt: type: string format: date-time securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: API Key ZeriqPay iniciada por `zeriq_`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.