Webhooks

A payment provider, a bank or a SaaS system sends its notifications as HTTP calls. In Weik.io a webhook is an api-version of type: webhook. It receives the calls on the gateway, publishes each request body, raw and unwrapped, into an event channel, and answers the caller only after the message is stored. Any integration that reads the channel reacts to it, now or after a restart, and a call is never lost between the gateway and your code.

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-received

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 is optional. A version without one publishes into a channel named after the API, which needs no document of its own and which subscriptions, browsing and re-sending treat like any other.

$ 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:

$ 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#

Every header the caller sent travels 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 exactly 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-notification

signatureCheck is a bean in the integration’s beans/ folder that computes the signature over the body with the provider’s secret, {{bank-webhook-secret}}, compares it with the header and fails the exchange when they differ. A failed exchange is delivered again after the read’s retry delays and lands in the dead letters after its last attempt.

Browse and re-send#

The stored calls are events of the channel. You list them with the API’s name, read one in full and send it again to the integration after you fixed a bug:

$ 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 can be at most 1 MiB, its body and headers together, so the gateway refuses a larger webhook body with 413. Webhook versions publish into the hub’s event stream, so they’re served by hub gateways. A gateway at a site serves proxy versions in front of the integrations there.