> ## Documentation Index
> Fetch the complete documentation index at: https://getconvoy.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Your First Webhook Event

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 [us dashboard](https://us.getconvoy.cloud/) or [eu dashboard](https://eu.getconvoy.cloud/). You'll also need your project ID which can be retrieved from your **Project Settings** page.

Your instance URL depends on where your project lives:

* Convoy Cloud (US): `https://us.getconvoy.cloud/api/v1`
* Convoy Cloud (EU): `https://eu.getconvoy.cloud/api/v1`
* Self-hosted: `https://your-instance/api/v1`

The Ruby gem is the one exception: it appends `/v1` itself, so `Convoy.base_uri` takes the URL **without** `/v1` (for example `https://us.getconvoy.cloud/api`). The Ruby tab below shows this.

<Tabs>
  <Tab title="Javascript">
    #### Install Client

    Install convoy.js with:

    ```bash terminal theme={null}
    npm install convoy.js
    ```

    #### Configure

    The client requires your instance URL, API key, and project ID.

    ```js example theme={null}
    const { Convoy } = require('convoy.js');

    const convoy = new Convoy({
    	uri: 'https://us.getconvoy.cloud/api/v1',
    	api_key: 'your_api_key',
    	project_id: 'your_project_id'
    });
    ```

    Now that your client has been configured, create an endpoint.

    #### Create an Endpoint

    ```js example theme={null}
    try {
    	const endpointData = {
    		name: 'default-endpoint',
    		url: 'https://example.com/webhooks/convoy',
    		description: 'Default Endpoint',
    		secret: 'endpoint-secret'
    	};

    	const response = await convoy.endpoints.create(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

    ```js example theme={null}
    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.

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

    	const response = await convoy.events.create(eventData);
    } catch (error) {
    	console.log(error);
    }
    ```
  </Tab>

  <Tab title="Python">
    #### Install Client

    Install convoy-python with:

    ```bash terminal theme={null}
    pip install convoy-python
    ```

    #### Configure

    `uri` is your instance API base; the client scopes requests to your project automatically.

    ```python example theme={null}
    from convoy import Convoy

    convoy = Convoy({
        "api_key": "your_api_key",
        "uri": "https://us.getconvoy.cloud/api/v1",
        "project_id": "your_project_id",
    })
    ```

    Now that your client has been configured, create an endpoint.

    #### Create an Endpoint

    Each method takes a query dict and returns a `(response, status)` tuple.

    ```python example theme={null}
    endpoint_data = {
        "name": "default-endpoint",
        "url": "https://example.com/webhooks/convoy",
        "description": "Default Endpoint",
        "secret": "endpoint-secret",
    }

    (response, status) = convoy.endpoint.create({}, endpoint_data)
    endpoint_id = response["data"]["uid"]
    ```

    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

    ```python example theme={null}
    subscription_data = {
        "name": "event-sub",
        "endpoint_id": endpoint_id,
    }

    (response, status) = convoy.subscription.create({}, subscription_data)
    ```

    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.

    ```python example theme={null}
    event_data = {
        "endpoint_id": endpoint_id,
        "event_type": "payment.success",
        "data": {
            "status": "Completed",
            "description": "Transaction Successful",
            "userID": "test_user_id808",
        },
    }

    (response, status) = convoy.event.create({}, event_data)
    ```
  </Tab>

  <Tab title="Ruby">
    #### Install Client

    Install convoy.rb with:

    ```bash terminal theme={null}
    gem install convoy.rb
    ```

    #### Configure

    To configure your client, provide your instance URL, api\_key and project\_id, see below:

    ```ruby theme={null}
    require 'convoy'

    Convoy.base_uri = "https://us.getconvoy.cloud/api"
    Convoy.api_key = "CO.M0aBe..."
    Convoy.project_id = "23b1..."
    ```

    #### Create an Endpoint

    An endpoint represents a target URL to receive webhook events. You should create one endpoint per user/business or whatever scope works well for you.

    ```ruby theme={null}
    endpoint = Convoy::Endpoint.new(
      data: {
        "name": "default-endpoint",
        "description": "Endpoint One",
        "http_timeout": "1m",
        "url": "https://example.com/webhooks/convoy"
      }
    )

    endpoint_response = endpoint.save
    ```

    #### Subscribe for Events

    After creating an endpoint, we need to subscribe the endpoint to events.

    ```ruby theme={null}
    subscription = Convoy::Subscription.new(
      data: {
        endpoint_id: endpoint_id,
        name: 'ruby subscription'
      }
    )

    subscription_response = subscription.save
    ```

    #### Send an Event

    To send an event, you'll need to pass the uid from the endpoint we created earlier.

    ```ruby theme={null}
    event = Convoy::Event.new(
      data: {
        endpoint_id: endpoint_id,
        event_type: "wallet.created",
        data: {
          status: "completed",
          event_type: "wallet.created",
          description: "transaction successful"
        }
      }
    )

    event_response = event.save
    ```
  </Tab>

  <Tab title="Golang">
    #### Install Client

    Install convoy-go, with:

    ```bash terminal theme={null}
    go get github.com/frain-dev/convoy-go/v2
    ```

    #### Configure

    The client takes your instance URL, API key, and project ID.

    ```go example theme={null}
    import (
        "context"

        convoy "github.com/frain-dev/convoy-go/v2"
    )

    ctx := context.Background()

    c := convoy.New("https://us.getconvoy.cloud/api/v1", "your_api_key", "your_project_id")
    ```

    #### Create an Endpoint

    ```go example theme={null}
    endpoint, err := c.Endpoints.Create(ctx, &convoy.CreateEndpointRequest{
        Name:        "default-endpoint",
        URL:         "https://example.com/webhooks/convoy",
        Description: "Default Endpoint",
    }, nil)
    if err != nil {
        log.Fatal("failed to create endpoint \n", err)
    }
    ```

    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

    ```go example theme={null}
    subscription, err := c.Subscriptions.Create(ctx, &convoy.CreateSubscriptionRequest{
        Name:       "event-sub",
        EndpointID: endpoint.UID,
    })
    if err != nil {
        log.Fatal("failed to create subscription \n", err)
    }
    ```

    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.

    ```go example theme={null}
    err = c.Events.Create(ctx, &convoy.CreateEventRequest{
        EndpointID: endpoint.UID,
        EventType:  "payment.success",
        Data:       []byte(`{"status": "Completed", "description": "Transaction Successful"}`),
    })
    if err != nil {
        log.Fatal("failed to create event \n", err)
    }
    ```
  </Tab>

  <Tab title="cURL">
    Sending webhooks with the API does not require a client setup like the SDKs. The API key retrieved from your dashboard will be added to the Authorization header and the project ID will be added to the request URL.

    #### Create an Endpoint

    An endpoint is a specific destination that can receive webhook events. Once you create an endpoint, you'll receive a uid as part of the response that you should save and supply in subsequent API calls to perform other requests such as creating an event.

    ```bash terminal theme={null}
    curl --request POST \
      --url https://{region}.getconvoy.cloud/api/v1/projects/<project-id>/endpoints \
      --header 'Authorization: Bearer <api-key>' \
      --header 'Content-Type: application/json' \
      --data '
        {
          "name": "Convoy endpoint",
          "description": "Endpoint description",
          "http_timeout": "10s",
          "url": "https://example.com/webhooks/convoy"
      }'
    ```

    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

    ```bash terminal theme={null}
    curl --request POST \
      --url https://{region}.getconvoy.cloud/api/v1/projects/<project-id>/subscriptions \
      --header 'Authorization: Bearer <api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
        "endpoint_id": "<endpoint-id>",
        "name": "Subscription name"
    }'
    ```

    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.

    ```bash terminal theme={null}
    curl --request POST \
      --url https://{region}.getconvoy.cloud/api/v1/projects/<project-id>/events \
      --header 'Authorization: Bearer <api-key>' \
      --header 'Content-Type: application/json' \
      --data '{
        "endpoint_id": "<endpoint-id>",
        "event_type": "payment.success",
        "data": {
          "event": "payment.success",
          "data": {
            "status": "Completed",
            "description": "Transaction Successful",
            "userID": "test_user_id808"
          }
        }
    }'
    ```
  </Tab>
</Tabs>

### Cheers! 🎉

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