{"id":20180785,"url":"https://github.com/frain-dev/convoy-go","last_synced_at":"2025-04-10T05:09:15.010Z","repository":{"id":42076874,"uuid":"406747525","full_name":"frain-dev/convoy-go","owner":"frain-dev","description":"The official Go SDK for Convoy (getconvoy.io)","archived":false,"fork":false,"pushed_at":"2024-10-28T14:37:35.000Z","size":285,"stargazers_count":15,"open_issues_count":2,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-24T06:21:55.776Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://getconvoy.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frain-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-15T12:07:22.000Z","updated_at":"2024-10-28T14:34:40.000Z","dependencies_parsed_at":"2023-10-16T03:28:05.710Z","dependency_job_id":"8146648e-c7f2-4c6c-be21-8f2b88c1618d","html_url":"https://github.com/frain-dev/convoy-go","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frain-dev%2Fconvoy-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frain-dev%2Fconvoy-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frain-dev%2Fconvoy-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frain-dev%2Fconvoy-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frain-dev","download_url":"https://codeload.github.com/frain-dev/convoy-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161271,"owners_count":21057555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T02:32:55.970Z","updated_at":"2025-04-10T05:09:14.989Z","avatar_url":"https://github.com/frain-dev.png","language":"Go","readme":"# convoy-go \u003cbr /\u003e [![Go Reference](https://pkg.go.dev/badge/github.com/frain-dev/convoy-go.svg)](https://pkg.go.dev/github.com/frain-dev/convoy-go/v2)\nThis 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)\n\n## Installation\n```bash\n$ go get github.com/frain-dev/convoy-go/v2\n```\n\n## Usage\nTo begin you need to define a Client. \n\n### Configure your Client\nBelow are the several ways you can configure a client depending on your needs. \n\n```go\nbaseURL := \"{host}/api/v1\"\n\n// Regular Client\nc := convoy.New(baseURL, apiKey, projectID)\n\n// Add a Custom HTTP Client\nclient := \u0026http.Client{}\nc := convoy.New(baseURL, apiKey, projectID,\n    convoy.OptionHTTPClient(client))\n\n// Add a SQS Client \nso := \u0026convoy.SQSOptions{\n    Client: sqs.New(),\n    QueueUrl: \"queue-url\",\n}\nc := convoy.New(baseURL, apiKey, projectID,\n    convoy.OptionSQSOptions(so))\n\n// Add a Kafka Client \nko := \u0026convoy.KafkaOptions{\n    Client: \u0026kafka.Client{},\n    Topic: \"kafka-topic\",\n}\nc := convoy.New(baseURL, apiKey, projectID,\n    convoy.OptionKafkaOptions(ko))\n```\nPlease see [go reference](https://pkg.go.dev/github.com/frain-dev/convoy-go) for other options available to use to configure your client.\n\n### Creating Endpoints \n```go\nbody := \u0026convoy.CreateEndpointRequest{\n    Name: \"endpoint-name\",\n    URL: \"http://play.getconvoy.io/ingest/DQzxCcNKTB7SGqzm\",\n    Secret: \"endpoint-secret\",\n    SupportEmail: \"notifications@getconvoy.io\"\n}\n\nendpoint, err := c.Endpoints.Create(ctx, body, nil)\nif err != nil {\n    return err\n}\n```\nStore the Endpoint ID, so you can use it in subsequent requests for creating subscriptions or sending events.\n\n### Creating Subscriptions\n```go \nbody := \u0026convoy.CreateSubscriptionRequest{\n    Name: \"endpoint-subscription\",\n    EndpointID: \"endpoint-id\",\n    FilterConfig: \u0026convoy.FilterConfiguration{\n        EventTypes: []string{\"*\"},\n    },\n}\n\nsubscription, err := c.Subscriptions.Create(ctx, body)\nif err != nil {\n    return err \n}\n```\n\n### Sending Events\nYou 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.\n\n#### HTTP\n```go\n// Send an event to a single endpoint.\nbody := \u0026CreateEventRequest{\n    EventType: \"event.type\",\n    EndpointID: \"endpoint-id\",\n    IdempotencyKey: \"unique-event-id\",\n    Data: []byte(`{\"version\": \"Convoy v24.0.0\"}`),\n}\n\nevent, err := c.Events.Create(ctx, body)\nif err != nil {\n    return err \n}\n\n// Send event to multiple endpoints.\nbody := \u0026CreateFanoutEventRequest{\n    EventType: \"event.type\",\n    OwnerID: \"unique-user-id\",\n    IdempotencyKey: \"unique-event-id\",\n    Data: []byte(`{\"version\": \"Convoy v24.0.0\"}`),\n}\n\nevent, err := c.Events.FanoutEvent(ctx, body)\nif err != nil {\n    return err \n}\n```\n\n**Note:** The body struct used above is the same used for the message brokers below.\n\n#### SQS \n```go \n// Send event to a single endpoint.\nerr := c.SQS.WriteEvent(ctx, body)\nif err != nil {\n    return err \n}\n\n// Send event to multiple endpoints.\nerr := c.SQS.WriteFanoutEvent(ctx, body)\nif err != nil {\n    return err \n}\n```\n\n#### Kafka \nThis library depends on [kafka-go](https://github.com/segmentio/kafka-go) to configure Kafka Clients. \n```go \n// Send event to a single endpoint.\nerr := c.Kafka.WriteEvent(ctx, body)\nif err != nil {\n    return err \n}\n\n\n// Send event to multiple endpoints.\nerr := c.Kafka.WriteFanoutEvent(ctx, body) \nif err != nil {\n    return err \n}\n```\n\n### Verifying Webhooks\nThis 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. \n```go \nwebhook := NewWebhook(\u0026convoy.ConfigOpts{\n    SigHeader: \"ZmBgy+E0i7x+yY9Ok92P3CZQkc+FEJgR5gYZ0bwSEhwLESnc/gGct57IQ==\",\n    Payload:   []byte(`{\"firstname\":\"test\",\"lastname\":\"test\"}`),\n    Secret:    \"8IX9njirDG\",\n    Hash:      \"SHA512\",\n    Encoding:  \"base64\",\n})\n\nerr := webhook.Verify()\nif err != nil {\n    return err \n}\n```\n\n### Version Compatibility Table\nThe following table identifies which version of the Convoy API is supported by this (and past) versions of this repo (convoy-go)\n\n| convoy-go Version | Convoy API Version |\n|-------------------|--------------------|\n| v2.1.5            | 0001-01-01         |\n| v2.1.6            | 0001-01-01         |\n| v2.1.7            | 0001-01-01         |\n\n## Credits\n- [Frain](https://github.com/frain-dev)\n\n## License\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrain-dev%2Fconvoy-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrain-dev%2Fconvoy-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrain-dev%2Fconvoy-go/lists"}