Skip to main content

​
Webhook Event Types

SwiftPay sends webhooks for various events in your account. Each event follows a standard envelope structure.

​
Webhook Structure

Every webhook request sent by SwiftPay has the following structure:
FieldTypeDescription
idstringUnique event identifier (e.g., evt_abc123)
typestringThe type of event (e.g., checkout.succeeded)
createdstringISO 8601 timestamp of when the event occurred
dataobjectEvent-specific payload (see below for types)

​
Expected Response

Your server should return a 2xx HTTP status code (e.g., 200 OK, 201 Created, 204 No Content) to acknowledge receipt of the webhook.
  • Timeouts: SwiftPay waits up to 30 seconds for a response.
  • Retries: If your server returns any other status code (e.g., 4xx, 5xx) or the request times out, SwiftPay will retry the delivery according to the retry schedule.
  • Body: The response body is ignored, but we recommend returning a short string like OK.

​
Headers

Each request includes security headers for verification:
HeaderDescription
X-Webhook-SignatureHMAC SHA-256 signature for verification. Format: t={timestamp},v1={signature}
User-AgentSwiftPay-Webhooks/1.0

​
Checkout Events

​
checkout.succeeded

Occurs when a checkout session is successfully completed and payment is received. 
{
   "id": "evt_checkout_abc123",
   "type": "checkout.succeeded",
   "created": "2024-01-15T10:30:00Z",
   "data": {
      "sessionId": "sess_abc123",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "customerEmail": "[email protected]",
      "customerName": "John Doe",
      "timestamp": "2024-01-15T10:30:00Z",
      "shipping": {
         "addressLine1": "123 Main St",
         "city": "San Francisco",
         "state": "CA",
         "postalCode": "94102",
         "country": "US"
      }
   }
}

​
Payload Fields

FieldTypeDescription
sessionIdstringUnique checkout session identifier
amountintegerTotal amount in cents
amountInDecimalsstringTotal amount formatted as decimal (e.g. “29.99”)
currencystringThree-letter ISO currency code
customerEmailstringEmail address of the customer
customerNamestringFull name of the customer
timestampstringISO 8601 timestamp of completion
shippingobjectShipping address details (if collected)

​
checkout.failed

Occurs when a checkout session fails (e.g., payment declined). 
{
   "id": "evt_checkout_def456",
   "type": "checkout.failed",
   "created": "2024-01-15T10:35:00Z",
   "data": {
      "sessionId": "sess_def456",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "customerEmail": "[email protected]",
      "errorMessage": "Insufficient funds",
      "failedAt": "2024-01-15T10:35:00Z"
   }
}

​
Payload Fields

FieldTypeDescription
sessionIdstringUnique checkout session identifier
amountintegerTotal amount in cents
amountInDecimalsstringTotal amount formatted as decimal (e.g. “29.99”)
currencystringThree-letter ISO currency code
customerEmailstringEmail address of the customer
errorMessagestringReason for the payment failure
failedAtstringISO 8601 timestamp of failure

​
Refund Events

​
refund.completed

Occurs when a refund is successfully processed. 
{
   "id": "evt_refund_def456",
   "type": "refund.completed",
   "created": "2024-01-15T11:05:00Z",
   "data": {
      "refundId": "ref_abc123",
      "sessionId": "sess_abc123",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "completedAt": "2024-01-15T11:05:00Z"
   }
}

​
Payload Fields

FieldTypeDescription
refundIdstringUnique refund identifier
sessionIdstringOriginal checkout session identifier
amountintegerRefund amount in cents
amountInDecimalsstringRefund amount formatted as decimal (e.g. “29.99”)
currencystringThree-letter ISO currency code
completedAtstringISO 8601 timestamp of completion

​
refund.failed

Occurs when a refund attempt fails. 
{
   "id": "evt_refund_ghi789",
   "type": "refund.failed",
   "created": "2024-01-15T11:10:00Z",
   "data": {
      "refundId": "ref_abc123",
      "sessionId": "sess_abc123",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "errorMessage": "Processor error",
      "failedAt": "2024-01-15T11:10:00Z"
   }
}

​
Payload Fields

FieldTypeDescription
refundIdstringUnique refund identifier
sessionIdstringOriginal checkout session identifier
amountintegerRefund amount in cents
amountInDecimalsstringRefund amount formatted as decimal (e.g. “29.99”)
currencystringThree-letter ISO currency code
errorMessagestringReason for the refund failure
failedAtstringISO 8601 timestamp of failure

​
Withdrawal Events

​
withdrawal.paid

Occurs when a withdrawal has been successfully paid out. 
{
   "id": "evt_withdrawal_def456",
   "type": "withdrawal.paid",
   "created": "2024-01-16T09:00:00Z",
   "data": {
      "withdrawalId": "wd_abc123",
      "amount": 50000,
      "amountInDecimals": "500.00",
      "currency": "USD",
      "destinationType": "bank_account",
      "completedAt": "2024-01-16T09:00:00Z"
   }
}

​
Payload Fields

FieldTypeDescription
withdrawalIdstringUnique withdrawal identifier
amountintegerWithdrawal amount in cents
amountInDecimalsstringWithdrawal amount formatted as decimal (e.g. “500.00”)
currencystringThree-letter ISO currency code
destinationTypestringType of destination (e.g. bank_account, crypto)
completedAtstringISO 8601 timestamp of completion

​
withdrawal.failed

Occurs when a withdrawal attempt fails. 
{
   "id": "evt_withdrawal_ghi789",
   "type": "withdrawal.failed",
   "created": "2024-01-16T09:05:00Z",
   "data": {
      "withdrawalId": "wd_abc123",
      "amount": 50000,
      "amountInDecimals": "500.00",
      "currency": "USD",
      "errorMessage": "Invalid bank details",
      "failedAt": "2024-01-16T09:05:00Z"
   }
}

​
Payload Fields

FieldTypeDescription
withdrawalIdstringUnique withdrawal identifier
amountintegerWithdrawal amount in cents
amountInDecimalsstringWithdrawal amount formatted as decimal (e.g. “500.00”)
currencystringThree-letter ISO currency code
errorMessagestringReason for the withdrawal failure
failedAtstringISO 8601 timestamp of failure