In this guide, you’ll learn how to deploy your first webhook event with Convoy. You’ll be making use of your project API key which can be generated by creating a project from your dashboard. You’ll also need your project ID which can be retrieved from your Project Settings page.

Install Client

Install convoy.js with:

terminal
npm install convoy.js

Configure

example
const { Convoy } = require('convoy.js');
const convoy = new Convoy({ api_key: 'your_api_key' });

In the event you’re using a self-hosted convoy instance, you can define the url as part of what is passed into convoy’s constructor.

example
const convoy = new Convoy({
	api_key: 'your_api_key',
	uri: 'self-hosted-instance'
});

Now that your client has been configured, create a convoy application.

Create an Endpoint

example
try {
	const endpointData = {
		url: 'https://0d87-102-89-2-172.ngrok.io',
		description: 'Default Endpoint',
		secret: 'endpoint-secret',
		events: ['*']
	};

	const response = await convoy.endpoints.create(appId, endpointData);
} catch (error) {
	console.log(error);
}

The next step is to create a subscription to the webhook source. Subscriptions are the conduit through which events are routed from a source to a destination on Convoy.

Subscribe for Events

example
try {
	const subscriptionData = {
		name: 'event-sub',
		endpoint_id: endpoint_id
	};

	const response = await convoy.subscriptions.create(subscriptionData);
} catch (error) {
	console.log(error);
}

With the subscription in place, you’re set to send an event.

Send an Event

To send an event, you’ll need the uid from the endpoint you created earlier.

example
try {
	const eventData = {
		endpoint_id: endpoint_id,
		event_type: 'payment.success',
		data: {
			event: 'payment.success',
			data: {
				status: 'Completed',
				description: 'Transaction Successful',
				userID: 'test_user_id808'
			}
		}
	};

	const response = await convoy.events.create(eventData);
} catch (error) {
	console.log(error);
}

​
Cheers! 🎉

You have successfully created a Convoy application to send events to your configured endpoint.

Was this page helpful?