zio-webhooks
zio-webhooks copied to clipboard
A microlibrary for reliable and persistent webhook delivery
ZIO Webhooks
ZIO Webhooks is a microlibrary for reliable and persistent webhook delivery.
Introduction
Below is a state diagram for each webhook handled by a server. Note that there aren't any initial or final states as the server doesn't manage the entire lifecycle of webhooks and events—only the subset needed for reliable webhook delivery.
Installation
Include ZIO Webhooks in your project by adding the following to your build.sbt
:
libraryDependencies += "dev.zio" %% "zio-webhooks" % "0.2.1"
Getting Started
There are two ways to start a webhook server: as part of the managed construction of its live layer
WebhookServer.live
, or manually by calling WebhookServer.start
. See examples for a list of code
examples. The managed approach is recommended as it guarantees the server shuts down gracefully. Make sure to
call shutdown
on a server created manually. Either way, users will have to implement the following dependencies that are part of WebhookServer
's environment:
-
WebhookRepo
- to get webhooks and update webhook status; -
WebhookEventRepo
- to subscribe to events and update event status; -
WebhookHttpClient
- to deliver events via HTTP POST (docs/WebhookSttpClient is provided and ready to use); -
WebhookServerConfig
- to specify settings for error hub capacity, retrying, and batching; and -
SerializePayload
- for specifying custom serialization of single and batched event payloads of some content type.
stateDiagram-v2
Enabled --> Disabled : disabled externally
Enabled --> Enabled : event dispatch success
Disabled --> Enabled : enabled externally
Enabled --> Retrying : event dispatch failure
Retrying --> Enabled : retry queue emptied
Retrying --> Unavailable : continuous failure for duration D
Unavailable --> Enabled : enabled externally
Unavailable --> Disabled : disabled externally
Example Programs
- Basic example - most basic usage with the default configuration.
- Basic example with batching - same as the basic example but with batching enabled.
- Basic example with retrying - shows how the server retries when an endpoint fails sometimes.
- Custom config example - a custom configuration example that also showcases batched retries.
- Event recovery example - shows how the server continues retries after being restarted.
- Manual server example - shows how to create, start, and shut down a server programmatically.
- Shutdown on first error - shows how to shut down the server on the first error encountered.
Documentation
Learn more on the ZIO Webhooks homepage!
Contributing
For the general guidelines, see ZIO contributor's guide.
Code of Conduct
See the Code of Conduct
Support
License
License