Webhook Overview

Webhooks are HTTP callbacks that notify your application when specific events occur in the Paystand system. They provide real-time notifications about payment status changes, transaction updates, and other important events.

How Webhooks Work

When an event occurs (such as a payment being completed), Paystand sends an HTTP POST request to your specified webhook URL with event details in JSON format.

Event Structure

All webhook events follow a consistent structure:

{
  "object": "event",
  "id": "unique_event_id",
  "resource": {
    // The updated resource (payment, refund, etc.)
  },
  "diff": {
    "previous": {
      // Previous state of the resource
    },
    "changes": {
      // What changed in this event
    }
  },
  "urls": ["your_webhook_url"],
  "sent": false,
  "lastAttemptSent": false,
  "attempts": 0,
  "sourceId": "resource_id",
  "sourceType": "ResourceType",
  "status": "active",
  "created": "2025-07-11T21:34:56.000Z",
  "lastUpdated": "2025-07-11T21:34:57.000Z"
}

Auto-Retry Mechanism

Paystand implements a robust retry mechanism to ensure webhook delivery:

Max Retries

Total number of attempts before marking the event as failed

• 8 attempts total

Retry Intervals

Fixed predefined intervals:

• 1st retry: 300 seconds (5 minutes)
• 2nd retry: 900 seconds (15 minutes)
• 3rd retry: 3600 seconds (1 hour)
• 4th retry: 43200 seconds (12 hours)
• 5th-8th retry: 86400 seconds (24 hours each)

Failure Conditions

Status codes triggering retry: Any response outside 200-299 status code range is considered as a failure and the auto-retry mechanism will be activated.

Status codes stopping retry immediately:

• 404 (Not Found)
• Invalid URL errors

Request timeout: 15 seconds per request

Event Types

Paystand supports the following webhook event types:

• Payment Events: Payment lifecycle notifications
• Receivable Transaction Events: Payment application to invoices
• Refund Events: Refund processing notifications
• Dispute Events: Chargeback and dispute updates
• Transfer Events: Payout and settlement notifications
• Fee Events: Merchant fee confirmations

Best Practices

1. Idempotency: Handle duplicate events gracefully
2. Response Time: Respond within 15 seconds
3. Status Codes: Return 2xx to let our system know of successful processing
4. Error Handling: Log failures in your system for debugging
5. Event Ordering: Don't rely on event order; use timestamps