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,
}

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://rampnetwork.github.io/assets/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://rampnetwork.github.io/assets/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://rampnetwork.github.io/assets/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://rampnetwork.github.io/assets/misc/test-logo.png',
variant: 'auto',
webhookStatusUrl: 'https://my.domain/callback/123/', // <- that's it!
}).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 query param.

Example:

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