Webhooks

A webhook forwards events Chronicle observes to an external HTTP endpoint — use it to notify another system without that system needing to connect to Chronicle itself. Webhooks are configured server-side (the Kernel makes the HTTP calls), so registering one is a one-time setup step, not something you do per request.

Register a webhook

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Webhooks;

[EventType]
public record WebhooksIndexAccountOpened(string OwnerName);

public class WebhooksIndexRegister(IEventStore eventStore)
{
    public async Task RegisterWebhook() =>
        await eventStore.Webhooks.Register(
            "account-events",
            "https://example.com/chronicle/webhooks",
            builder => builder
                .WithEventType<WebhooksIndexAccountOpened>()
                .WithHeader("x-source", "my-app")
                .WithBearerToken(Environment.GetEnvironmentVariable("WEBHOOK_TOKEN")!));
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.Events.WebhooksIndexAccountOpened do
  use Chronicle.Events.EventType, id: "webhooks-index-account-opened"

  defstruct [:owner_name]
end

defmodule MyApp.WebhooksIndexRegister do
  alias MyApp.Events.WebhooksIndexAccountOpened

  def register_webhook do
    Chronicle.WebHooks.register(
      "account-events",
      "https://example.com/chronicle/webhooks",
      fn builder ->
        builder
        |> Chronicle.WebHooks.DefinitionBuilder.with_event_type(WebhooksIndexAccountOpened)
        |> Chronicle.WebHooks.DefinitionBuilder.with_header("x-source", "my-app")
        |> Chronicle.WebHooks.DefinitionBuilder.with_bearer_token(System.fetch_env!("WEBHOOK_TOKEN"))
      end
    )
  end
end

TypeScript

import { eventType, IEventStore } from '@cratis/chronicle';

@eventType()
class WebhooksIndexAccountOpened {
    constructor(readonly ownerName: string) {}
}

class WebhooksIndexRegister {
    constructor(
        private readonly store: IEventStore,
        private readonly webhookToken: string
    ) {}

    async registerWebhook(): Promise<void> {
        await this.store.webhooks.register(
            'account-events',
            'https://example.com/chronicle/webhooks',
            builder => {
                builder
                    .withEventType(WebhooksIndexAccountOpened)
                    .withHeader('x-source', 'my-app')
                    .withBearerToken(this.webhookToken);
            }
        );
    }
}

If no event types are configured, the webhook forwards every event type registered for the client.

Query registered webhooks

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Webhooks;

public class WebhooksIndexQuery(IEventStore eventStore)
{
    public async Task<IEnumerable<WebhookDefinition>> GetAllWebhooks() => await eventStore.Webhooks.GetAll();
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule MyApp.WebhooksIndexQuery do
  def get_all_webhooks do
    Chronicle.WebHooks.all()
  end
end

TypeScript

import { IEventStore } from '@cratis/chronicle';
import { WebhookDefinition } from '@cratis/chronicle.contracts';

class WebhooksIndexQuery {
    constructor(private readonly store: IEventStore) {}

    async getAllWebhooks(): Promise<WebhookDefinition[]> {
        return this.store.webhooks.getWebhooks();
    }
}

Kotlin and Java don’t currently have a webhooks API — there’s no equivalent anywhere in the Kotlin client SDK yet.

Related topics

• Jobs — inspecting and controlling long-running Kernel operations, the other kernel-managed background concern.
• Subscriptions — forwarding events between event stores rather than to an external HTTP endpoint.