zio / zio-webhooks   0.2.1

Apache License 2.0 GitHub

A microlibrary for reliable and persistent webhook delivery

Scala versions: 2.13 2.12

ZIO Webhooks

ZIO Webhooks is a microlibrary for reliable and persistent webhook delivery.

Development CI Badge Sonatype Releases Sonatype Snapshots javadoc ZIO Webhooks


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.


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.

    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


Learn more on the ZIO Webhooks homepage!


For the general guidelines, see ZIO contributor's guide.

Code of Conduct

See the Code of Conduct


Come chat with us on Badge-Discord.