> ## Documentation Index > Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Register webhook > Registers a notification endpoint for the selected events. The URL is verified at registration. ## OpenAPI ````yaml /openapi.yaml post /webhooks openapi: 3.0.3 info: title: Fincle API version: 1.0.0 description: >- Fincle payments API: charges by Pix, credit card and boleto, subscriptions, transactions, refunds, infractions, notifications and transfers. servers: - url: https://api.fincle.com.br description: Production server security: [] tags: - name: Authentication description: Issuance of the access token from the API key. - name: Charges description: Creation of charges by Pix, credit card and boleto. - name: Subscriptions description: Recurring billing on credit card. - name: Transactions description: Retrieval and refund of transactions. - name: Refunds description: Refund requests submitted by payers. - name: Infractions and MED description: Pix infraction reports and the amounts blocked as a result. - name: Webhooks description: Registration of notification endpoints and tracking of deliveries. - name: Balance and transfers description: Balance, statement, fees and transfer of the amounts received. paths: /webhooks: post: tags: - Webhooks summary: Register webhook description: >- Registers a notification endpoint for the selected events. The URL is verified at registration. operationId: createWebhook requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: URL that receives the POST for each subscribed event. events: type: array items: type: string enum: - transaction_created - transaction_paid - transaction_refunded - transaction_updated - transfer_completed - transfer_canceled - transfer_created - transfer_updated - infraction - card_declined - sale_lost - cart_abandoned - product_canceled - release_access - vturb_paid - vk_metrics_purchase - refund_requested minItems: 1 maxItems: 17 description: >- Events subscribed by this endpoint. At least one is required. name: type: string minLength: 1 maxLength: 255 description: Label of the webhook, used to recognize it in the list. isActive: type: boolean default: true description: '`false` registers the webhook already paused.' productIds: type: array items: type: string pattern: ^[cC][^\s-]{8,}$ maxItems: 50 description: >- Restricts the webhook to these products. When omitted, it applies to all products of the account. offerIds: type: array items: type: integer exclusiveMinimum: true minimum: 0 maxItems: 50 description: >- Restricts the webhook to these offers. When omitted, it applies to all offers. required: - url - events additionalProperties: false example: url: https://api.example.com/webhooks/fincle events: - transaction_paid - transaction_refunded name: Financial management system isActive: true responses: '201': description: Webhook registered. content: application/json: schema: type: object properties: success: type: boolean description: Always `true` in a successful response. data: type: object properties: id: type: integer description: Webhook identifier. name: type: string nullable: true description: >- Label of the webhook, used to recognize it in the list. url: type: string description: URL that receives the POST for each subscribed event. events: type: array items: type: string enum: - transaction_created - transaction_paid - transaction_refunded - transaction_updated - transfer_completed - transfer_canceled - transfer_created - transfer_updated - infraction - card_declined - sale_lost - cart_abandoned - product_canceled - release_access - vturb_paid - vk_metrics_purchase - refund_requested description: Events subscribed by this endpoint. isActive: type: boolean description: >- `false` pauses deliveries without deleting the registration. productIds: type: array items: type: string description: >- Products that trigger this webhook. An empty list means all products of the account. offerIds: type: array items: type: integer description: >- Offers that trigger this webhook. An empty list means all offers. signatureSecretMasked: type: string description: >- HMAC signing secret, masked: only the last 4 characters are shown. mtlsCapable: type: boolean description: >- `true` when the endpoint accepts mTLS with the Fincle certificate. createdAt: type: string format: date-time description: Time at which the webhook was registered. updatedAt: type: string description: Time of the last change. format: date-time required: - id - name - url - events - isActive - productIds - offerIds - signatureSecretMasked - mtlsCapable - createdAt - updatedAt additionalProperties: false required: - success - data additionalProperties: false description: Webhook registered. example: success: true data: id: 412 name: Financial management system url: https://api.example.com/webhooks/fincle events: - transaction_paid - transaction_refunded isActive: true productIds: [] offerIds: [] signatureSecretMasked: ••••••••9f2c mtlsCapable: false createdAt: '2026-08-14T11:02:00.000Z' updatedAt: '2026-09-08T16:40:00.000Z' '400': description: The request is well formed, but a business rule rejected it. content: application/json: schema: type: object properties: success: type: boolean description: Always `false` in an error response. message: type: string description: Readable message explaining the failure. required: - success - message additionalProperties: false description: The request is well formed, but a business rule rejected it. example: success: false message: Não foi possivel testar a url do webhook '401': description: Token missing, invalid, expired or belonging to a blocked account. content: application/json: schema: type: object properties: success: type: boolean description: Always `false` in an error response. message: type: string description: Readable message explaining the failure. required: - success - message additionalProperties: false description: >- Token missing, invalid, expired or belonging to a blocked account. example: success: false message: Token inválido ou expirado '422': description: The request did not pass schema validation. content: application/json: schema: type: object properties: success: type: boolean description: Always `false` in an error response. message: type: string description: Readable message explaining the failure. required: - success - message additionalProperties: false description: The request did not pass schema validation. example: success: false message: 'name: Nome é obrigatório' '429': description: >- Too many requests: the limit is 1000 requests per minute per source IP. Wait the number of seconds given in the `retry-after` header and retry with exponential backoff. content: application/json: schema: type: object properties: success: type: boolean description: Always `false` in an error response. message: type: string description: Readable message explaining the failure. required: - success - message additionalProperties: false description: >- Too many requests: the limit is 1000 requests per minute per source IP. Wait the number of seconds given in the `retry-after` header and retry with exponential backoff. example: success: false message: Muitas requisições. Tente novamente em breve. headers: retry-after: $ref: '#/components/headers/retry-after' x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' '500': description: >- Internal failure while processing the request. Retry; if it persists, open a support ticket stating the time and the route. content: application/json: schema: type: object properties: success: type: boolean description: Always `false` in an error response. message: type: string description: Readable message explaining the failure. required: - success - message additionalProperties: false description: >- Internal failure while processing the request. Retry; if it persists, open a support ticket stating the time and the route. example: success: false message: Erro interno do servidor security: - bearerAuth: [] components: headers: retry-after: description: Seconds to wait before repeating the request. schema: type: integer x-ratelimit-limit: description: >- Maximum number of requests in the window (1000). Present in every response. schema: type: integer x-ratelimit-remaining: description: >- Number of requests still available in the current window. Present in every response. schema: type: integer x-ratelimit-reset: description: Seconds until the window counter resets. Present in every response. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.