Overview

The Webhook API provides a comprehensive solution for receiving real-time notifications about events in our system, like payment status updates, and other important events in lifecycle of our services. Webhooks enable your application to stay synchronized with payment events without the need for constant polling.

What are Webhooks?

Webhooks are HTTP callbacks that are triggered by specific events in the system. When a relevant event occurs (such as a payment confirmation, refund processing, or charge status change), the system automatically sends an HTTP POST request to your configured webhook URL with detailed information about the event.

🚀 Key Benefits

Real-time Notifications: Receive instant updates about payment events
Reduced Server Load: No need to constantly poll for status updates
Better User Experience: Immediate feedback for payment confirmations
Automated Processing: Trigger business logic based on payment events
Reliability: Built-in retry mechanisms for failed deliveries

📋 Supported Webhook Types

Webhook Types

Type	Description
`PIX_OUTBOUND`	Notifications for outbound Pix transfers
`PIX_QR_INBOUND`	Payment confirmation via dynamic QR Code
`PIX_QR_PARTNER_INBOUND`	Partner Pix QR Code payment notifications
`CARD_PAYMENT_INBOUND`	Credit/debit card payment confirmations
`CARD_CHARGEBACK`	Chargeback dispute notifications submitted by customers
`CARD_RECURRING_INBOUND`	Confirmation of recurring credit card charges (e.g., subscriptions)
`PAYMENT_LINK_INBOUND`	Payment link transaction confirmations

- The payload for each webhook type is in the Webhook section of each product.

🎯 Use Cases

E-commerce Integration

Payment Confirmations: Automatically update order status when payments are received
Refund Processing: Handle customer refunds and update inventory
Subscription Management: Process recurring payments and renewals

Financial Services

Transaction Monitoring: Track payment status in real-time
Compliance Reporting: Generate reports for regulatory requirements
Risk Management: Monitor for suspicious activities

Business Automation

Inventory Management: Update stock levels after successful payments
Customer Notifications: Send confirmation emails and SMS
Analytics Integration: Feed payment data to business intelligence systems

Webhook API - Testing and Validation

Overview

This document provides comprehensive testing guidelines and validation procedures for the Webhook API. It includes endpoint testing, authentication setup, and validation scenarios to ensure proper webhook integration.

🔧 Getting Started

Prerequisites

Valid Astrapay account
API credentials (client ID and secret)

Authentication

All API requests require OAuth 2.0 authentication using a Bearer token obtained here.

Base URLs

Sandbox: https://api-sandbox.astrapay.com.br/webhook/v1
Production: https://api.astrapay.com.br/webhook/v1

Common Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id> (optional - UUID generated by the client)

📡 API Endpoints

1. List All Webhooks

GET /webhook/v1/list

Retrieves all registered webhooks for your account.

Query Parameters

Parameter	Type	Required	Description
`eventType`	string	No	Filter by event type
`page`	integer	No	Page number (default: 0)
`size`	integer	No	Page size (default: 20)

Request Headers

Authorization: Bearer <your_access_token>
x-transaction-id: <unique_transaction_id>

Response

{
  "content": [
    {
      "webhookId": 1,
      "customerId": 123,
      "partnerId": 67890,
      "targetUrl": "https://yourdomain.com/webhook/pix",
      "eventType": "PIX_OUTBOUND",
      "isActive": true
    },
    {
      "webhookId": 2,
      "customerId": 123,
      "partnerId": 67890,
      "targetUrl": "https://yourdomain.com/webhook/card",
      "eventType": "CARD_PAYMENT_INBOUND",
      "isActive": true
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "first": true,
  "last": true,
  "empty": false
}

2. Create Webhook

POST /webhook/v1/create

Creates a new webhook configuration.

Request Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json
x-transaction-id: <unique_transaction_id>

Request Body

{
  "partnerId": 67890,
  "targetUrl": "https://yourdomain.com/webhook",
  "eventType": "PIX_QR_INBOUND",
  "isActive": true
}

Field	Type	Required	Description
`partnerId`	integer	No	Partner ID
`targetUrl`	string	Yes	Target URL to receive webhooks
`eventType`	string	Yes	Webhook event type
`isActive`	boolean	No	Indicates if the webhook is active

Response

{
  "webhookId": 1,
  "customerId": 123,
  "partnerId": 67890,
  "targetUrl": "https://yourdomain.com/webhook",
  "eventType": "PIX_QR_INBOUND",
  "isActive": true
}

3. Find Webhook by ID

GET /webhook/v1/{id}

Retrieves a specific webhook configuration by ID.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Webhook ID

Response

{
  "webhookId": 1,
  "customerId": 123,
  "partnerId": 67890,
  "targetUrl": "https://yourdomain.com/webhook",
  "eventType": "PIX_QR_INBOUND",
  "isActive": true
}

4. Update Webhook

PUT /webhook/v1/{id}

Updates an existing webhook configuration.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Webhook ID

Request Body

{
  "targetUrl": "https://yourdomain.com/new-webhook-url",
  "eventType": "CARD_CHARGEBACK",
  "isActive": true
}

Response

{
  "webhookId": 1,
  "customerId": 123,
  "partnerId": 67890,
  "targetUrl": "https://yourdomain.com/new-webhook-url",
  "eventType": "CARD_CHARGEBACK",
  "isActive": true
}

5. Delete Webhook

DELETE /webhook/v1/{id}

Deletes a webhook configuration.

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Webhook ID

Response

204 No Content

6. List Webhook Results

GET /webhook/v1/list/results

Retrieves webhook delivery results and history.

Query Parameters

Parameter	Type	Required	Description
`eventType`	string	No	Filter by event type
`page`	integer	No	Page number (default: 0)
`size`	integer	No	Page size (default: 20)

Response

{
  "content": [],
  "totalElements": 0,
  "totalPages": 0,
  "size": 20,
  "number": 0,
  "first": true,
  "last": true,
  "empty": true
}

📋 Supported Event Types

Event Type	Description
`PIX_OUTBOUND`	Outbound Pix transfer notifications
`PIX_QR_INBOUND`	Dynamic QR Code payment confirmations
`PIX_QR_PARTNER_INBOUND`	Partner Pix QR Code payment notifications
`CARD_PAYMENT_INBOUND`	Credit/debit card payment confirmations
`CARD_CHARGEBACK`	Chargeback dispute notifications
`CARD_RECURRING_INBOUND`	Recurring credit card charge confirmations
`PAYMENT_LINK_INBOUND`	Payment link transaction confirmations