Skip to main content
Webhooks provide real-time notifications when events occur in your Gnosis Ramp integration. Instead of polling, your server receives HTTP POST requests when statuses change.

​
Event Types

EventDescription
INTENT_STATUS_CHANGEDIntent transitions to a new status
COMPLIANCE_UPDATEDCompliance requirement status changes
MONEY_MOVEMENT_UPDATEDTransaction status changes

​
Setting Up Webhooks

  1. Go to your project in the Gnosis Ramp Dashboard
  2. Navigate to Settings → Webhooks
  3. Enter your webhook endpoint URL
  4. Copy the signing secret for signature verification

​
Webhook Delivery

  • Method: POST
  • Content-Type: application/json
  • Timeout: 30 seconds
Your endpoint should return a 2xx status code to acknowledge receipt.

​
Retry Policy

If delivery fails, Gnosis Ramp retries with exponential backoff:
AttemptDelay
11 minute
25 minutes
330 minutes
42 hours
524 hours
6Final attempt
After 6 failed attempts, the webhook is marked as exhausted and no further retries occur.

​
Delivery Guarantees

  • At-least-once delivery: Events may be delivered more than once
  • Use eventId for deduplication: Each event has a unique ID
  • No ordering guarantees: Events may arrive out of order

​
Example Payload

{
  "eventId": "evt_abc123",
  "eventType": "INTENT_STATUS_CHANGED",
  "timestamp": "2026-03-29T10:00:00.000Z",
  "projectId": "proj_xyz789",
  "data": {
    "intentId": "int_def456",
    "status": "COMPLIANCE_APPROVED",
    "previousStatus": "COMPLIANCE_IN_PROGRESS"
  }
}

​
Best Practices

  1. Verify signatures — Always validate the webhook signature before processing
  2. Respond quickly — Return 2xx immediately, process asynchronously if needed
  3. Handle duplicates — Use eventId to detect and ignore duplicate deliveries
  4. Log everything — Store raw payloads for debugging and audit

​
Next Steps

Signature Verification

Secure your webhook endpoint.

Event Reference

See all event types and payloads.