Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Webhooks

Weik.io 2026.2

A webhook API version stores each call's body in a channel before it answers. Product page · Video

Watch: Webhooks, 3:09

The video receives a webhook into a channel. An integration then reads the receipts from the channel.

On this page

Use a webhook version when a system such as a payment provider or a bank sends its notifications as HTTP calls. An api-version of type: webhook receives the calls on the gateway and publishes each request body into an event channel as the caller sent it. The gateway answers the caller only after the message is stored. An integration that listens on the channel also gets the calls that arrived while it was stopped.

The API and its webhook version#

finance/apis/bank-notifications.yaml
apiVersion: weik.io/v1
kind: api
metadata: { name: bank-notifications, project: finance }
spec: { displayName: Bank notifications, prefix: /bank-notifications }
---
apiVersion: weik.io/v1
kind: api-version
metadata: { name: v1, project: finance, api: bank-notifications }
spec:
  type: webhook
  channel: bank-notification-received
finance/events/bank-notification-received.yaml
apiVersion: weik.io/v1
kind: event-channel
metadata: { name: bank-notification-received, project: finance }
spec:
  description: One event per notification the bank sends, the body as the bank sent it

The channel field is optional. Without it, a version publishes into a channel named after the API. That channel needs no document and works like any other channel.

Terminal
$ weikio apply -f ./finance/apis/ -f ./finance/events/
$ weikio api deploy finance/bank-notifications@v1 --env production

Give the sender a credential#

The sender needs a subscription like any caller. Many providers let you set a URL with a key in it, which a queryparameter subscription accepts:

Terminal
$ weikio subscription create finance/bank --env production --api bank-notifications --type queryparameter

The provider then calls https://api.example.com/bank-notifications/v1?x-api-key=<the key>. A provider that signs in with a username and password gets a basic subscription instead.

The headers travel with the body#

The headers the caller sent travel with the message, prefixed Weikio-Hook-, except the key or password that let the caller in. A provider’s X-Signature header reaches your integration as Weikio-Hook-X-Signature, beside the body as the provider signed it.

bank-notification-handler/routes/on-notification.camel.yaml
- route:
    from:
      uri: "kamelet:weikio-event-source?channel=bank-notification-received"
      steps:
        - to: bean:signatureCheck
        - log: "Notification ${header.Weikio-Hook-X-Request-Id} accepted"
        - to: direct:process-notification

signatureCheck is a bean in the integration’s beans/ folder. It computes the signature over the body with the provider’s secret, {{bank-webhook-secret}}, and fails the exchange when the signature differs from the header.

A failed exchange is delivered again after the retry delays of the integration’s delivery settings. After the last attempt, it lands in the dead letters.

Browse and re-send#

The stored calls are events of the channel. You can list them by the API’s name or open one. After you fix a bug in the integration, send a call to it again:

Terminal
$ weikio events list finance/bank-notification-received --env production --family hook --api bank-notifications --since 24h
$ weikio events resend finance/bank-notification-received --env production --seq 48213 --to finance/bank-notification-handler

Limits#

An event’s body and headers together can be at most 1 MiB, so a call with a larger body gets 413.

Where webhooks are served#

Only hub gateways serve webhook versions. A gateway at a site serves proxy versions in front of the integrations there.

Sign in to the live demo

Sign in with the shared viewer account. It can open every screen of the example projects but can't change anything.

E-mail
viewer@demo.weik.io
Password
try-weikio-live-demo
Open the live demo