Webhooks Reference

This reference provides an overview of the Getnet Webhook system, including authentication methods, available event types, API endpoints, and webhook payload structures. For detailed API endpoint documentation with request/response schemas, parameters, and examples, refer to the API Reference documentation.

Getnet sends webhook notifications as HTTP POST requests with JSON payloads. All timestamps use ISO 8601 format, and monetary amounts are in the smallest currency unit (cents for BRL).

Authentication

When creating a webhook subscription, you must specify how Getnet should authenticate when posting to your endpoint. The Webhook Management API supports three authentication methods:

1. User Credentials (Basic Auth)

When Getnet sends webhooks to your endpoint, it will include:

2. OAuth 2.0

Use this method when your webhook endpoint expects OAuth 2.0 Bearer tokens. Getnet will execute the full OAuth 2.0 client credentials flow on your behalf before each webhook delivery.

When Getnet sends webhooks, it will:

1. Request a token from your OAuth server using the provided credentials
2. Extract the token from the response using token_key_name
3. Include it in the webhook request: Authorization: Bearer {token}

3. Token (Bearer Token)

Use this method when you want Getnet to use a Bearer token obtained from the Getnet Authentication API. This token is the same one you use to authenticate API requests to Getnet.

Note: The token is obtained from the Getnet Authentication API endpoint (/authentication/oauth2/access_token) using your client_id and client_secret. This is the same token you use for other Getnet API requests. See the Authentication documentation for details on obtaining tokens from the authentication endpoint.

When Getnet sends webhooks, it will include:

Event Types

Getnet webhooks support the following event types. Each event type corresponds to a specific transaction state or action:

When creating a webhook subscription, you specify which event type(s) you want to receive. You can create multiple subscriptions for different event types or handle all events at a single endpoint.

Webhook Management API Overview

The Webhook Management API provides endpoints to manage your webhook subscriptions programmatically. For complete endpoint documentation including request/response schemas, parameters, error codes, and examples, see the API Reference.

Available Endpoints

Base URL

All webhook management endpoints are available at:

For detailed information about each endpoint, including:

• Request and response schemas
• Required and optional parameters
• Query parameters and pagination
• Error responses and status codes
• Example requests and responses

Refer to the API Reference documentation.

Webhook Event Payloads

APPROVED_TRANSACTIONS

Sent when a payment transaction has been successfully approved.

---

REJECTED_TRANSACTIONS

Sent when a payment transaction has been rejected or denied.

---

REFUNDED_TRANSACTIONS

Sent when a transaction has been refunded.

---

CANCELLED_TRANSACTIONS

Sent when a transaction has been cancelled.

---

CAPTURED_TRANSACTIONS

Sent when a pre-authorized payment has been captured.

---

CARD_UPDATE

Sent when card details are updated via Network Token or Account Updater services.

CHARGEBACK_NEEDS_RESPONSE

Upon receiving this event, the recommended flow is:

1. Extract the dispute_id from each item in the array.
2. Call 4.7 Chargeback Details to retrieve the full dispute data (see the Chargeback API reference page for details).
3. Upload supporting evidence via 4.8 Documents (see the Chargeback API reference page for details).
4. Submit the contestation via POST /disputes/{dispute_id}/evidences.

Batching: If more than 100 disputes are queued for notification, Getnet delivers them in multiple requests, each containing up to 100 items in the array.

Response Requirements

Your webhook endpoint must:

• Accept HTTP POST requests
• Use HTTPS with a valid SSL certificate
• Respond with HTTP status code 204 (No Content) to acknowledge successful receipt
• Handle authentication as configured in your subscription

Important Notes

1. Idempotency: All webhook payloads include an idempotency_key. Your endpoint should be idempotent and handle duplicate deliveries gracefully.
2. Response Code: Your webhook endpoint must respond with HTTP 204 (No Content) to acknowledge successful receipt. Any other status code will be considered a failure.
3. Timestamps: All timestamps are in ISO 8601 format (e.g., 2025-11-13T14:30:00.000Z).
4. Amounts: Monetary amounts are represented in the smallest currency unit (cents for BRL).
5. Optional Fields: Some fields may be null or omitted depending on the transaction type and payment method.
6. Retry Logic: If your endpoint doesn't respond with 204, Getnet will retry the webhook delivery.