Webhooks
Set up webhooks to receive real-time payment notifications. SpacePay signs webhooks using HMAC-SHA256 with the formattimestamp + "." + rawBody.
Webhook Setup: Webhooks are set up in your admin dashboard under Settings → Developers →
Webhooks. Each webhook endpoint gets its own unique secret key for signature verification.
Webhook Event Types
SpacePay sends the following webhook events:payment.created: Payment has been created and is ready for customer paymentpayment.updated: Payment status has been updated (confirmed, failed, expired, etc.)withdrawal.created: Withdrawal has been created and is ready for customer paymentwithdrawal.updated: Withdrawal status has been updated (confirmed, failed, expired, etc.)
Webhook Payload Structure
Webhook payloads contain a minimal snapshot of the resource. If you need full details — such as
quotes, deposit address, or receipt — call Get Payment or Get Withdrawal from the API
reference using the
id from the payload.- Payment
- Withdrawal
Webhook Headers
SpacePay includes these headers with each webhook:X-SpacePay-Id: Webhook endpoint IDX-SpacePay-Event-Id: Unique event identifierX-SpacePay-Timestamp: Timestamp when webhook was sentX-SpacePay-Delivery-Id: Unique delivery attempt IDX-SpacePay-Signature: HMAC-SHA256 signature
Signature Verification
Webhook Handler Implementation
Webhook Setup
1
Access Webhook Settings
Navigate to Settings → Developers → Webhooks in your admin dashboard.
2
Add Webhook Endpoint
Enter your webhook URL (must be HTTPS) to receive payment notifications.
3
Test Your Endpoint
Use the test webhook feature to verify your endpoint is working correctly.
4
Save Webhook Secret
Copy the webhook secret and store it securely in your environment variables.
Security Best Practices
Always Verify Signatures
Never process webhook events without verifying the signature first.
Use HTTPS
Webhook endpoints must use HTTPS to ensure secure data transmission.
Idempotency
Handle duplicate webhook deliveries gracefully using event IDs.
Timeout Handling
Respond to webhooks quickly (within 30 seconds) to avoid timeouts.
Next Steps
SDK Integration
Use our official SDK for easier integration.
API Integration
Integrate directly with SpacePay’s REST APIs.
Testing
Learn about test environments and scenarios.
Support
Get help with your integration from our support team.