Skip to main content
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.
  • Javascript
  • Ruby
  • Golang
  • cURL

​
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',
	uri: 'your_uri'
});
In the event you’re using a self-hosted convoy instance, you can add your instance uri. But if you are using the cloud base service, your uri will either be the following base on the region you register as:
  • https://us.getconvoy.cloud/api/v1
  • https://eu.getconvoy.cloud/api/v1
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.