Webhooks
Weik.io 2026.2A 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.
This part of the video couldn't be loaded.
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#
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-receivedapiVersion: 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 itThe 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.
$ weikio apply -f ./finance/apis/ -f ./finance/events/
$ weikio api deploy finance/bank-notifications@v1 --env productionGive 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:
$ weikio subscription create finance/bank --env production --api bank-notifications --type queryparameterThe 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.
- 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-notificationsignatureCheck 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:
$ 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-handlerLimits#
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.