https://github.com/frain-dev/convoy-go
The official Go SDK for Convoy (getconvoy.io)
https://github.com/frain-dev/convoy-go
Last synced: 12 months ago
JSON representation
The official Go SDK for Convoy (getconvoy.io)
- Host: GitHub
- URL: https://github.com/frain-dev/convoy-go
- Owner: frain-dev
- License: mit
- Created: 2021-09-15T12:07:22.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-28T14:37:35.000Z (over 1 year ago)
- Last Synced: 2025-03-24T06:21:55.776Z (about 1 year ago)
- Language: Go
- Homepage: https://getconvoy.io
- Size: 278 KB
- Stars: 15
- Watchers: 2
- Forks: 9
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# convoy-go
[](https://pkg.go.dev/github.com/frain-dev/convoy-go/v2)
This is the Golang SDK for Convoy. It makes it easy to interact with the Convoy API. You can view the full API Reference [here](https://convoy.readme.io/reference)
## Installation
```bash
$ go get github.com/frain-dev/convoy-go/v2
```
## Usage
To begin you need to define a Client.
### Configure your Client
Below are the several ways you can configure a client depending on your needs.
```go
baseURL := "{host}/api/v1"
// Regular Client
c := convoy.New(baseURL, apiKey, projectID)
// Add a Custom HTTP Client
client := &http.Client{}
c := convoy.New(baseURL, apiKey, projectID,
convoy.OptionHTTPClient(client))
// Add a SQS Client
so := &convoy.SQSOptions{
Client: sqs.New(),
QueueUrl: "queue-url",
}
c := convoy.New(baseURL, apiKey, projectID,
convoy.OptionSQSOptions(so))
// Add a Kafka Client
ko := &convoy.KafkaOptions{
Client: &kafka.Client{},
Topic: "kafka-topic",
}
c := convoy.New(baseURL, apiKey, projectID,
convoy.OptionKafkaOptions(ko))
```
Please see [go reference](https://pkg.go.dev/github.com/frain-dev/convoy-go) for other options available to use to configure your client.
### Creating Endpoints
```go
body := &convoy.CreateEndpointRequest{
Name: "endpoint-name",
URL: "http://play.getconvoy.io/ingest/DQzxCcNKTB7SGqzm",
Secret: "endpoint-secret",
SupportEmail: "notifications@getconvoy.io"
}
endpoint, err := c.Endpoints.Create(ctx, body, nil)
if err != nil {
return err
}
```
Store the Endpoint ID, so you can use it in subsequent requests for creating subscriptions or sending events.
### Creating Subscriptions
```go
body := &convoy.CreateSubscriptionRequest{
Name: "endpoint-subscription",
EndpointID: "endpoint-id",
FilterConfig: &convoy.FilterConfiguration{
EventTypes: []string{"*"},
},
}
subscription, err := c.Subscriptions.Create(ctx, body)
if err != nil {
return err
}
```
### Sending Events
You can send events to Convoy via HTTP or via any supported message broker. See [here](https://www.getconvoy.io/docs/manual/sources#Message%20Brokers) to see the list of supported brokers.
#### HTTP
```go
// Send an event to a single endpoint.
body := &CreateEventRequest{
EventType: "event.type",
EndpointID: "endpoint-id",
IdempotencyKey: "unique-event-id",
Data: []byte(`{"version": "Convoy v24.0.0"}`),
}
event, err := c.Events.Create(ctx, body)
if err != nil {
return err
}
// Send event to multiple endpoints.
body := &CreateFanoutEventRequest{
EventType: "event.type",
OwnerID: "unique-user-id",
IdempotencyKey: "unique-event-id",
Data: []byte(`{"version": "Convoy v24.0.0"}`),
}
event, err := c.Events.FanoutEvent(ctx, body)
if err != nil {
return err
}
```
**Note:** The body struct used above is the same used for the message brokers below.
#### SQS
```go
// Send event to a single endpoint.
err := c.SQS.WriteEvent(ctx, body)
if err != nil {
return err
}
// Send event to multiple endpoints.
err := c.SQS.WriteFanoutEvent(ctx, body)
if err != nil {
return err
}
```
#### Kafka
This library depends on [kafka-go](https://github.com/segmentio/kafka-go) to configure Kafka Clients.
```go
// Send event to a single endpoint.
err := c.Kafka.WriteEvent(ctx, body)
if err != nil {
return err
}
// Send event to multiple endpoints.
err := c.Kafka.WriteFanoutEvent(ctx, body)
if err != nil {
return err
}
```
### Verifying Webhooks
This client supports verifying [simple](https://www.getconvoy.io/docs/manual/signatures#Simple%20signatures) and [advanced](https://www.getconvoy.io/docs/manual/signatures#Advanced%20signatures) webhook signatures.
```go
webhook := NewWebhook(&convoy.ConfigOpts{
SigHeader: "ZmBgy+E0i7x+yY9Ok92P3CZQkc+FEJgR5gYZ0bwSEhwLESnc/gGct57IQ==",
Payload: []byte(`{"firstname":"test","lastname":"test"}`),
Secret: "8IX9njirDG",
Hash: "SHA512",
Encoding: "base64",
})
err := webhook.Verify()
if err != nil {
return err
}
```
### Version Compatibility Table
The following table identifies which version of the Convoy API is supported by this (and past) versions of this repo (convoy-go)
| convoy-go Version | Convoy API Version |
|-------------------|--------------------|
| v2.1.5 | 0001-01-01 |
| v2.1.6 | 0001-01-01 |
| v2.1.7 | 0001-01-01 |
## Credits
- [Frain](https://github.com/frain-dev)
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.