Skip to main content

Events

Ramp allows you to track the various events that occur during an end-user's journey through our app. Here's a write-up of ones that might help you.

Event types​

Events fall into two major categories - widget status events and purchase status events.

Widget status events​

Those events are dispatched to your SDK instance - they aren't available via webhooks.

WIDGET_CLOSE​

Sent when the widget is closed.

{
  type: 'WIDGET_CLOSE',
  payload: null,
  widgetInstanceId: string,
}

WIDGET_CONFIG_DONE​

Sent when the widget is done fetching the internal configuration and can be displayed. This is when the loader hides.

NOTE: this is done automatically, you can call .show() immediately without waiting for this event.

{
  type: 'WIDGET_CONFIG_DONE',
  payload: null,
  widgetInstanceId: string,
}

WIDGET_CONFIG_FAILED​

Sent when the widget has failed fetching the internal configuration. This is when the loader hides.

NOTE: it's done automatically, you can call .show() immediately without waiting for this event.

{
  type: 'WIDGET_CONFIG_FAILED',
  payload: null,
  widgetInstanceId: string,
}

WIDGET_CLOSE_REQUEST​

Sent when a user wants to close the widget and a confirmation modal is displayed.

{
  type: 'WIDGET_CLOSE_REQUEST',
  payload: null,
  widgetInstanceId?: string,
}

WIDGET_CLOSE_REQUEST_CANCELLED​

Sent when a user cancels closing the widget window.

{
  type: 'WIDGET_CLOSE_REQUEST_CANCELLED',
  payload: null,
}

WIDGET_CLOSE_REQUEST_CONFIRMED​

Sent when a user confirms closing the widget - this ends the flow.

{
  type: 'WIDGET_CLOSE_REQUEST_CONFIRMED',
  payload: null,
}

Purchase created status event​

This event is sent when a purchase is created.

PURCHASE_CREATED​

{
  type: 'PURCHASE_CREATED',
  payload: {
    purchase: RampPurchase,
    purchaseViewToken: string,
    apiUrl: string
  },
  widgetInstanceId: string,
}

Off-ramp Sale created status event​

This event is sent when a purchase is created.

{
  type: 'OFFRAMP_SALE_CREATED',
  payload: {
    sale: RampSale,
    saleViewToken: string,
    apiUrl: string
  },
  widgetInstanceId: string,
}

Subscribing to events​

We provide two ways of subscribing to events - via our SDK and via webhooks.

Subscribing via SDK​

Let's see how to subscribe to Ramp events using our SDK.

A basic integration of Ramp via our SDK looks like this.

new RampInstantSDK({
  hostAppName: 'Your App',
  hostLogoUrl: 'https://assets.ramp.network/misc/test-logo.png',
  variant: 'auto',
}).show();

In order to subscribe to events, call the .on(eventType, callback) method of the SDK instance.

new RampInstantSDK({
  hostAppName: 'Your App',
  hostLogoUrl: 'https://assets.ramp.network/misc/test-logo.png',
  variant: 'auto',
})
  .on('*', (event) => console.log(event))
  .show();

You can subscribe to all events by using '*' as the first argument to .on() or subscribe to particular event types by passing their name, like so.

new RampInstantSDK({
  hostAppName: 'Your App',
  hostLogoUrl: 'https://assets.ramp.network/misc/test-logo.png',
  variant: 'auto',
})
  .on('WIDGET_CLOSE', (event) => console.log(event))
  .show();

In order to unsubscribe from a given event type, just call .unsubscribe() using the same params you called .on() with.

Subscribing via webhooks​

Subscribing to events via webhooks depends on how you've integrated Ramp into your app.

Integration via SDK​

If you've integrated Ramp via our SDK, you just need to provide a URL to be used for webhook status updates.

new RampInstantSDK({
  hostAppName: 'Your App',
  hostLogoUrl: 'https://assets.ramp.network/misc/test-logo.png',
  variant: 'auto',
  webhookStatusUrl: 'https://my.domain/callback/123/', // <- that's it! (for purchase)
  offrampWebhookV3Url: 'https://my.domain/callback/123/', // <- that's it! (for sale)
}).show();

Integration via URL - hosted mode only​

If you've chosen to integrate Ramp via URL, you'll need to provide a URL for webhook status updates via a webhookStatusUrl or offrampWebhookV3Url query param.

Examples:

https://app.ramp.network/?webhookStatusUrl=https://example.com/webhook/
https://app.ramp.network/?offrampWebhookV3Url=https://example.com/webhook/