Skip to main content

Webhook Authentication

API data

API Gateway
This API is used for payment gateway operations:

Description​

Endpoints responsible for managing Basic authentication credentials used by the Webhook service.

The system already sends the Access-Key header to identify the sender. Additionally, you can register or remove an extra Basic authentication that will be automatically included in the webhook request headers.

Automatic webhooks

When a payment is processed, our platform can automatically send a notification to your application with the transaction data. Basic authentication adds an extra layer of security for these notifications.

Learn more about Webhooks →

🔐 Endpoints​

➕ Register Webhook Authentication​

POST /v1/security/webhook-auth

Registers a Basic authentication that will be automatically included in webhook request headers.

Request
{
  "basic": "Basic <Base64>"
}

Data dictionary - Parameters​

PROPERTYDESCRIPTIONTYPELOCATIONREQUIREDVALIDATION
basicBasic authentication credential in the format Basic <Base64>StringBodyyesMust start with Basic and contain valid Base64

Validation rules​

  • The basic field is required

  • It must start with Basic

  • The content after Basic must be valid Base64

  • Only one active credential is allowed per client

    Authentication registered successfully
    {
      "message": "Autenticação de webhook cadastrada com sucesso"
    }

    Data dictionary - Response​

    PROPERTYDESCRIPTIONTYPE
    messageSuccess messagestring

➖ Delete Webhook Authentication​

DELETE /v1/security/webhook-auth

Removes the Basic authentication registered for the client.

Request
// No request body required
Authentication removed successfully
{
  "message": "Autenticação de webhook removida com sucesso"
}

Data dictionary - Response​

PROPERTYDESCRIPTIONTYPE
messageSuccess messagestring

HTTP headers​

Requests to the webhook authentication endpoints require Bearer authentication in the header:

Content-Type: application/json
Authorization: Bearer <token>

See also​

Response codes

If a transaction fails, check our full response-code table to identify and properly handle errors:

Authorizer Host Response Codes →

Webhooks

To understand how webhook notifications work and how to implement the receiver in your application:

Webhook Notifications →