Stax Disputes Webhook

Upswello receives dispute events from Stax via webhooks. This guide explains how to configure and handle these events.

Endpoint URL

Configure your Stax webhook to send dispute events to:

POST /api/webhook/stax/partner/disputes

Signature Verification

Stax signs webhook requests for security. The webhook handler verifies the signature using the configured secret.

⚠️Security

Always verify webhook signatures in production. Never process unsigned webhooks.

Idempotency

Webhook handlers are idempotent. Duplicate events are safely ignored based on unique identifiers in the payload.

Event Types

The webhook handles the following event types:

  • create_dispute - A new dispute has been created
  • update_dispute - An existing dispute has been updated

Payload Structure

Example webhook payload:

{
  "event_type": "create_dispute",
  "data": {
    "dispute_id": "...",
    "transaction_id": "...",
    "amount": "...",
    "reason": "...",
    "status": "..."
  }
}
ℹ️Payload Fields

The exact payload structure may vary. Refer to Stax documentation for the most current schema.

Response Format

The webhook handler always returns:

{
  "received": true
}

This ensures Stax does not retry successfully processed events.

Error Handling

If processing fails:

  1. The error is logged server-side
  2. A 200 OK response is still returned to prevent retry storms
  3. Failed events can be reprocessed manually if needed

Testing

Test your webhook configuration using Stax's webhook testing tools or by sending sample payloads to your endpoint.

On this page