> ## 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.

# SDK

Convoy provides SDKs for in-app integration. These SDKs carry out the same operations as the API and Convoy dashboard. The methods in each SDK mirror the [API](/api-reference).

This page introduces you to the SDKs as well as demonstrates the steps involved in sending an event to your Convoy instance. You will need your project API key and project ID, both available 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

    Next, require the convoy module and set it up with 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'
    });
    ```

    ### 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);
    }
    ```

    ### Create a Subscription

    ```js example theme={null}
    try {
        const subscriptionData = {
            name: 'event-sub',
            endpoint_id: endpointId
        };

        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

    ```js example theme={null}
    try {
        const eventData = {
            endpoint_id: endpointId,
            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

    Next, import the convoy module and set it up with your auth credentials. `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",
    })
    ```

    ### 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"]
    ```

    ### Create a Subscription

    ```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

    ```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

    Add this line to your application's Gemfile:

    ```ruby example theme={null}
    gem 'convoy.rb'
    ```

    And then execute:

    ```bash terminal theme={null}
    bundle install
    ```

    Or install it yourself as:

    ```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 example 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 example 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
    ```

    ### Create a Subscription

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

    ```ruby example 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 the `uid` from the endpoint we created earlier.

    ```ruby example 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)
    }
    ```

    ### Create a Subscription

    ```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 we 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>
</Tabs>

To verify webhook signatures on the receiving side with these SDKs, see the [receiving guide](/guides/receiving-webhook-example).

[Contribute to this doc in Github](https://github.com/frain-dev/convoy-website/blob/main/docs/sdk/sdk.mdx)

#### Don't miss anything.

Subscribe to the Convoy Newsletter find tutorials and tools that will help you grow as a developer and scale your project or business, and see interesting topics.