Webhook Configuration

Where the merchant registers their URL to receive status updates. Webhooks allow you to receive real-time notifications about payment events.

Overview

Configure webhooks to receive real-time notifications about payment events. When a payment status changes, we'll send a POST request to your configured URL with the event details.

Available Events:

payment.succeeded - Payment completed successfully
payment.failed - Payment was declined or failed
payment.pending - Payment is being processed
refund.completed - Refund has been processed
refund.failed - Refund could not be processed

Security:

Always verify webhook signatures to ensure requests are from Altafinex. Learn how to verify webhooks

Request

Request Body

Required and optional fields

url

required

The HTTPS URL where webhook events will be sent. Must be publicly accessible.

events

required

Array of event types you want to receive. See available events above.

secret

optional

Your webhook secret for signature verification. If not provided, one will be generated.

Code Examples

curl -X POST "https://api.altafinex.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://your-merchant-site.com/api/webhooks/payment",
  "events": [
    "payment.succeeded",
    "payment.failed",
    "refund.completed"
  ],
  "secret": "whsec_your_webhook_secret"
}'

Webhook Payload

Example Webhook Payload

What you'll receive when an event occurs

{
  "event": "payment.succeeded",
  "data": {
    "payment_id": "pay_1234567890abcdef",
    "status": "succeeded",
    "amount": 10000,
    "currency": "THB"
  },
  "timestamp": "2024-01-15T10:30:15Z"
}

Response

Status Codes

200

Webhook configured successfully

400

Invalid request data

401

Authentication failed

422

Invalid URL or unreachable endpoint

Success Response

Example response for a successful request

{
  "webhook_id": "wh_1234567890abcdef",
  "url": "https://your-merchant-site.com/api/webhooks/payment",
  "events": [
    "payment.succeeded",
    "payment.failed",
    "refund.completed"
  ],
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z"
}

Error Response

Example response for an error

{
  "error": {
    "code": "invalid_url",
    "message": "The webhook URL is invalid or unreachable",
    "type": "validation_error"
  }
}