# 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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#description/introduction) 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)

Use this method when your webhook endpoint validates requests using HTTP Basic Authentication. Getnet will include a standard `Authorization: Basic` header composed of the credentials you provide.

**Configuration:**

```json
{
  "authentication_type": "user_credentials",
  "authentication_data": {
    "user": "your_client_id",
    "password": "your_client_secret"
  }
}
```

When Getnet sends webhooks to your endpoint, it will include:
```
Authorization: Basic {base64_encoded_user:password}
```

### 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.

**Configuration:**

```json
{
  "authentication_type": "oauth",
  "authentication_data": {
    "oauth_url": "https://auth.provider.com/token",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "credentials_location": "basic_auth_header",
    "token_key_name": "access_token"
  }
}
```

**Configuration fields:**

| Field                  | Type   | Required | Description                                                                 |
| ---------------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `oauth_url`            | string | Yes      | OAuth token endpoint URL                                                    |
| `client_id`            | string | Yes      | OAuth client ID                                                             |
| `client_secret`        | string | Yes      | OAuth client secret                                                         |
| `credentials_location` | string | No       | Where to send credentials: `basic_auth_header` (default) or `body`          |
| `token_key_name`       | string | No       | Key name in token response (default: `access_token`)                       |

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.

**Configuration:**

```json
{
  "authentication_type": "token",
  "authentication_data": {
    "token": "your_bearer_token_from_getnet_auth_api"
  }
}
```

<Callout type="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](/en/global-api/sep-api/first-steps-api/authentication) for details on obtaining tokens from the authentication endpoint.

</Callout>

When Getnet sends webhooks, it will include:
```
Authorization: Bearer {token}
```

## Event Types

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

| Event Type                | Description                                                      |
| ------------------------- | ---------------------------------------------------------------- |
| `APPROVED_TRANSACTIONS`        | Payment transaction has been successfully approved                                  |
| `REJECTED_TRANSACTIONS`        | Payment transaction was rejected or denied                                          |
| `CAPTURED_TRANSACTIONS`        | Pre-authorized payment has been captured                                            |
| `CANCELLED_TRANSACTIONS`       | Transaction has been cancelled                                                      |
| `REVERSED_TRANSACTIONS`        | Card Present authorization has been reversed before capture                         |
| `REFUNDED_TRANSACTIONS`        | Transaction has been refunded                                                       |
| `CARD_UPDATE`                  | Card details updated via Network Token or Account Updater                           |
| `CARD_UPDATED_TRANSACTIONS`    | Card details updated on a transaction via Network Token or Account Updater          |
| `PENDING_TRANSACTIONS`         | Transaction is pending processing                                                   |
| `PIX_UPDATED_TRANSACTIONS`     | PIX transaction status has been updated                                             |
| `BOLETO_UPDATED_TRANSACTIONS`  | Boleto transaction status has been updated                                          |
| `BOLETO_PAID_TRANSACTIONS`     | Boleto has been paid                                                                |
| `PROCESSING_TRANSACTIONS`      | Transaction is being processed                                                      |
| `FAILED_TRANSACTIONS`          | Transaction processing has failed                                                   |
| `EXPIRED_TRANSACTIONS`         | Transaction has expired                                                             |
| `AUTHORIZED_TRANSACTIONS`      | Transaction has been authorized                                                     |

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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/webhooks).

### Available Endpoints

| Endpoint                                                      | Method | Description                                                      |
| ------------------------------------------------------------- | ------ | ---------------------------------------------------------------- |
| `POST /subscriptions`                                         | POST   | Create a new webhook subscription                                 |
| `GET /subscriptions/{event_name}`                       | GET    | Retrieve webhook subscriptions for a specific event name         |
| `DELETE /subscriptions/{event_name}`                    | DELETE | Delete a webhook subscription                                    |
| `GET /subscriptions/{event_name}/events`                 | GET    | List event messages for a subscription with pagination           |
| `PATCH /subscriptions/{event_name}/events/{event_id}`   | PATCH  | Resend a specific webhook event message                          |
| `GET /subscriptions-events`                                   | GET    | List all events you are currently subscribed to                  |

### Base URL

All webhook management endpoints are available at:
```
https://api.globalgetnet.com/dpm/webhooks/v1
```

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](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/webhooks) documentation.

## Webhook Event Payloads

When a subscribed event occurs, Getnet sends an HTTP POST request to your `callback_url` with a JSON payload containing the event data. The payload structure varies depending on the event type.

### APPROVED_TRANSACTIONS

Sent when a payment transaction has been successfully approved.

**Example Payload:**

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": "11870",
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2025-11-13T14:30:00.000Z",
  "transaction_id": "123456789012",
  "original_transaction_id": null,
  "authorized_at": "2025-11-13T14:30:00.000Z",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA",
  "brand": "Visa",
  "authorization_code": "123456",
  "acquirer_transaction_id": "987654321",
  "eci": "05",
  "payment_received_timestamp": "2025-11-13T14:30:00.000Z",
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  "merchant_advice_code": null,
  "additional_data": {}
}
```

**Field Descriptions:**

| Field                  | Type   | Description                                                      |
| ---------------------- | ------ | ----------------------------------------------------------------- |
| `idempotency_key`      | string | Idempotency key used to control requests                          |
| `seller_id`            | string | Seller identification                                              |
| `request_id`           | string | Request identifier. Unique for each request                       |
| `payment_id`           | string | Payment identifier                                                |
| `order_id`             | string | Purchase identification code used by e-commerce                  |
| `amount`               | string | Transaction amount                                                |
| `currency`             | string | Currency code (e.g., "BRL", "USD")                                |
| `status`               | string | Transaction status (e.g., "APPROVED")                             |
| `payment_method`       | string | Payment method used (e.g., "CREDIT", "DEBIT")                    |
| `received_at`          | string | Timestamp when payment was received                                |
| `transaction_id`       | string | Transaction identifier                                            |
| `original_transaction_id` | string | Original transaction identifier (for refunds/cancellations)   |
| `authorized_at`        | string | Timestamp when transaction was authorized                          |
| `reason_code`          | string | Return code from the sender or the getnet capture system          |
| `reason_message`       | string | Return message from the sender or the getnet capture system      |
| `acquirer`             | string | Acquirer name                                                      |
| `soft_descriptor`      | string | Soft descriptor shown on card statement                           |
| `brand`                | string | Card brand (e.g., "Visa", "Mastercard")                           |
| `authorization_code`   | string | Authorization code                                                 |
| `acquirer_transaction_id` | string | Acquirer transaction identifier                                |
| `eci`                  | string | Electronic Commerce Indicator                                      |
| `payment_received_timestamp` | string | Payment received timestamp                                    |
| `card_id`              | string | Card identifier saved in vault (if applicable)                    |
| `boleto`               | object | Boleto payment details (if applicable)                            |
| `merchant_advice_code` | string | Merchant advice code (if applicable)                              |
| `additional_data`      | object | Additional data                                                    |

---

### REJECTED_TRANSACTIONS

Sent when a payment transaction has been rejected or denied.

**Example Payload:**

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": "11870",
  "currency": "BRL",
  "status": "REJECTED",
  "payment_method": "CREDIT",
  "received_at": "2025-11-13T14:30:00.000Z",
  "transaction_id": "123456789012",
  "original_transaction_id": null,
  "authorized_at": null,
  "reason_code": "51",
  "reason_message": "INSUFFICIENT FUNDS",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA",
  "brand": "Visa",
  "authorization_code": null,
  "acquirer_transaction_id": null,
  "eci": null,
  "payment_received_timestamp": "2025-11-13T14:30:00.000Z",
  "card_id": null,
  "merchant_advice_code": null,
  "additional_data": {}
}
```

**Field Descriptions:**

| Field                  | Type   | Description                                                      |
| ---------------------- | ------ | ----------------------------------------------------------------- |
| `idempotency_key`      | string | Idempotency key used to control requests                          |
| `seller_id`            | string | Seller identification                                              |
| `request_id`           | string | Request identifier. Unique for each request                       |
| `payment_id`           | string | Payment identifier                                                |
| `order_id`             | string | Purchase identification code used by e-commerce                  |
| `amount`               | string | Transaction amount                                                |
| `currency`             | string | Currency code (e.g., "BRL", "USD")                                |
| `status`               | string | Transaction status (e.g., "REJECTED")                             |
| `payment_method`       | string | Payment method used (e.g., "CREDIT", "DEBIT")                    |
| `received_at`          | string | Timestamp when payment was received                                |
| `transaction_id`       | string | Transaction identifier                                            |
| `original_transaction_id` | string | Original transaction identifier (for refunds/cancellations)   |
| `authorized_at`        | string | Timestamp when transaction was authorized (may be null)            |
| `reason_code`          | string | Return code from the sender or the getnet capture system          |
| `reason_message`       | string | Return message from the sender or the getnet capture system      |
| `acquirer`             | string | Acquirer name                                                      |
| `soft_descriptor`      | string | Soft descriptor shown on card statement                           |
| `brand`                | string | Card brand (e.g., "Visa", "Mastercard")                           |
| `authorization_code`   | string | Authorization code (may be null)                                   |
| `acquirer_transaction_id` | string | Acquirer transaction identifier (may be null)                  |
| `eci`                  | string | Electronic Commerce Indicator (may be null)                        |
| `payment_received_timestamp` | string | Payment received timestamp                                    |
| `card_id`              | string | Card identifier saved in vault (if applicable, may be null)      |
| `boleto`               | object | Boleto payment details (if applicable)                            |
| `merchant_advice_code` | string | Merchant advice code (if applicable, may be null)                  |
| `additional_data`      | object | Additional data                                                    |

---

### REFUNDED_TRANSACTIONS

Sent when a transaction has been refunded.

**Example Payload:**

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": 8900,
  "currency": "BRL",
  "status": "REFUNDED",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "canceled_at": "2025-11-13T15:30:00.000Z",
  "custom_key": "20200630-8900"
}
```

**Field Descriptions:**

| Field            | Type   | Description                                                      |
| ---------------- | ------ | ----------------------------------------------------------------- |
| `idempotency_key` | string | Idempotency key, used to control requests (1-64 characters)      |
| `seller_id`      | string | ECommerce identification code (UUID, 36 characters)              |
| `request_id`     | string | Request identifier. Unique for each request (UUID, 36 characters) |
| `payment_id`     | string | Payment identifier (UUID, 36 characters)                        |
| `order_id`       | string | Purchase identification code used by e-commerce                  |
| `amount`         | number | Purchase value in cents                                          |
| `currency`       | string | Currency identification (e.g., "BRL")                            |
| `status`         | string | Transaction status                                               |
| `reason_code`    | string | Return code from the sender or the getnet capture system (2 chars) |
| `reason_message` | string | Return message from the sender or the getnet capture system      |
| `canceled_at`    | string | Cancellation/refund date (ISO 8601 format)                      |
| `custom_key`     | string | Customer key used to identify the refund request (3-32 chars)   |

---

### CANCELLED_TRANSACTIONS

Sent when a transaction has been cancelled.

**Example Payload:**

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": 8900,
  "currency": "BRL",
  "status": "CANCELLED",
  "reason_code": "00",
  "reason_message": "TRANSACTION CANCELLED SUCCESSFULLY",
  "canceled_at": "2025-11-13T15:30:00.000Z",
  "custom_key": "20200630-8900"
}
```

**Field Descriptions:**

| Field            | Type   | Description                                                      |
| ---------------- | ------ | ----------------------------------------------------------------- |
| `idempotency_key` | string | Idempotency key, used to control requests (1-64 characters)      |
| `seller_id`      | string | ECommerce identification code (UUID, 36 characters)              |
| `request_id`     | string | Request identifier. Unique for each request (UUID, 36 characters) |
| `payment_id`     | string | Payment identifier (UUID, 36 characters)                        |
| `order_id`       | string | Purchase identification code used by e-commerce                  |
| `amount`         | number | Purchase value in cents                                          |
| `currency`       | string | Currency identification (e.g., "BRL")                            |
| `status`         | string | Transaction status                                               |
| `reason_code`    | string | Return code from the sender or the getnet capture system (2 chars) |
| `reason_message` | string | Return message from the sender or the getnet capture system      |
| `canceled_at`    | string | Cancellation date (ISO 8601 format)                              |
| `custom_key`     | string | Customer key used to identify the cancellation request (3-32 chars)   |

---

### REVERSED_TRANSACTIONS

Sent when a Card Present authorization has been reversed before capture. A reversal always covers the full amount, and no money moves.

**Example Payload:**

```json
{
  "idempotency_key": "b10be7a7-d76e-4cd6-8ebe-4f68b9271d9c",
  "seller_id": "19ffd677-3691-4c4d-88c9-79cc91b95c0d",
  "request_id": "51d212f6-ad05-499c-90a1-e05c3b6ea0db",
  "payment_id": "b0b7851a-e558-4d94-b34e-86d69138de77",
  "order_id": "471994a7-ba22-453e-8afc-f0137d1710c2",
  "amount": 4000,
  "status": "REVERSED",
  "canceled_at": "2026-09-04T18:14:54.057Z",
  "reason_code": "00",
  "reason_message": "Payment successful reversal.",
  "custom_key": "2bc94fa13c8d4df28e52a996912bbab5",
  "authorization_code": "601878",
  "trace_number": 0,
  "complete_cancel": true,
  "callback_url": "https://myserver.com/send/callback/here"
}
```

**Field Descriptions:**

| Field                | Type    | Description                                                      |
| -------------------- | ------- | ----------------------------------------------------------------- |
| `idempotency_key`    | string  | Idempotency key sent on the reversal request (1-64 characters)    |
| `seller_id`          | string  | Seller identification (UUID, 36 characters)                       |
| `request_id`         | string  | Request identifier. Unique for each request (UUID, 36 characters) |
| `payment_id`         | string  | Identifier of the reversed payment (UUID, 36 characters)          |
| `order_id`           | string  | Purchase identification code (code or order number)              |
| `amount`             | number  | Reversed amount in cents. Always the full amount of the original authorization |
| `status`             | string  | Transaction status (`REVERSED`)                                   |
| `canceled_at`        | string  | Reversal date (ISO 8601 format)                                   |
| `reason_code`        | string  | Return code from the sender or the getnet capture system (2 chars) |
| `reason_message`     | string  | Return message from the sender or the getnet capture system      |
| `custom_key`         | string  | Customer key sent on the reversal request (3-32 chars)            |
| `authorization_code` | string  | Authorization code                                                |
| `trace_number`       | integer | Trace number of the transaction                                   |
| `complete_cancel`    | boolean | Indicates a full reversal. Always `true` for this event           |
| `callback_url`       | string  | Webhook URL that received this notification                       |

---

### CAPTURED_TRANSACTIONS

Sent when a pre-authorized payment has been captured.

**Example Payload:**

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb7",
  "seller_id": "9406df6c-3100-49ba-b4df-d81c1ad8a62b",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "payment_id": "2c341d28-491b-4cf8-aec7-eeb60136b7a5",
  "order_id": "ORDER-10187383",
  "amount": 8900,
  "currency": "BRL",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "TRANSACTION EXECUTED SUCCESSFULLY",
  "captured_at": "2025-11-13T16:00:00.000Z"
}
```

**Field Descriptions:**

| Field            | Type   | Description                                                      |
| ---------------- | ------ | ----------------------------------------------------------------- |
| `idempotency_key` | string | Idempotency key, used to control requests (1-64 characters)      |
| `seller_id`      | string | ECommerce identification code (UUID, 36 characters)              |
| `request_id`     | string | Request identifier. Unique for each request (UUID, 36 characters) |
| `payment_id`     | string | Payment identifier (UUID, 36 characters)                        |
| `order_id`       | string | Purchase identification code used by e-commerce                |
| `amount`         | number | Purchase value in cents                                          |
| `currency`       | string | Currency identification (e.g., "BRL")                           |
| `status`         | string | Transaction status                                               |
| `reason_code`    | string | Return code from the sender or the getnet capture system (2 chars) |
| `reason_message` | string | Return message from the sender or the getnet capture system    |
| `captured_at`    | string | Capture date (ISO 8601 format)                                  |

---

### CARD_UPDATE

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

**Example Payload:**

```json
{
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  "last_four_digits": "1212",
  "bin": "121212",
  "expiration_month": 12,
  "expiration_year": 28,
  "brand": "Mastercard",
  "cardholder_name": "JOAO DA SILVA",
  "customer_id": "customer_21081826",
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
  "used_at": "2017-04-19T16:30:30Z",
  "created_at": "2017-04-19T16:30:30Z",
  "updated_at": "2017-04-19T16:30:30Z",
  "status": "active",
  "transaction_id": "123456"
}
```

**Field Descriptions:**

| Field              | Type    | Description                                                      |
| ------------------ | ------- | ----------------------------------------------------------------- |
| `card_id`          | string  | Card identifier saved in the safe (max 36 chars)                 |
| `last_four_digits` | string  | Last four digits of the card (max 4 chars)                       |
| `bin`              | string  | First six digits of the card (max 6 chars)                       |
| `expiration_month` | integer | Two-digit card expiration month (1-12)                           |
| `expiration_year`  | integer | Two-digit card expiration year                                   |
| `brand`            | string  | Card banner (Mastercard, Visa, Amex, Elo, Hipercard)            |
| `cardholder_name`  | string  | Buyer's name printed on the card (max 26 chars)                  |
| `customer_id`      | string  | Buyer identifier (max 100 chars)                                 |
| `number_token`     | string  | Card token that will be used in transactions (max 128 chars)     |
| `used_at`          | string  | Date of last use (ISO 8601 format)                               |
| `created_at`       | string  | Creation date (ISO 8601 format)                                   |
| `updated_at`       | string  | Update date (ISO 8601 format)                                     |
| `status`           | string  | Card status in the safe (active, blocked, canceled, renewed)     |
| `transaction_id`   | string  | Card Verification Transaction ID (max 32 chars)                   |

## 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

If your endpoint returns any status code other than `204`, Getnet will consider the delivery failed and may retry the webhook delivery.

## 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.