Inbound webhooks

A provider that you use (a payment processor, an identity provider, a bank) reports what happens by webhook. An inbound webhook lets that provider send its webhooks directly to Kairos. Kairos checks each delivery, turns the payload into events and labels, and stores them. You write no code for it.

Provider ──POST──▶ /v1/webhooks/whk_…  ──▶ verify ──▶ mapping ──▶ events, labels
                                              │          │
                                              └──────────┴──▶ delivery log

• When to use it
• Your user id: the most important part
• Templates
• Connect Stripe
• Connect another provider
• The mapping
• Verification
• What Kairos answers, and the delivery log
• Limits and security
• The API

When to use it#

A webhook arrives after the fact. It adds history and outcomes; it does not make a decision before an action. For that, your server still calls decide.

Your user id: the most important part#

Decisions are about your ids (user_42). A provider knows its ids (cus_Nf3…). If the provider's events are stored on cus_Nf3…, a decision about user_42 does not see them. A mapping finds your id in one of three ways, from the best to the last resort:

1. Your id is in the payload. Most providers have a metadata field that you fill when you create an object. Put your user id there, and the mapping reads it: "user": "$.data.object.metadata.user_id".
2. Kairos finds it. The payload does not name your user, but Kairos already knows the connection:
   • From a record: "user": { "record": "$.data.object.payment_intent" } is the user on the earlier events of that record. A Stripe refund or dispute names its PaymentIntent, and the payment event of that PaymentIntent named the user.
   • From a property: "user": { "lookup": { "property": "stripe_customer_id", "value": "$.data.object.customer" } } is the user whose property stripe_customer_id is the customer id. You store it on the user once, with $set or PUT /v1/entities/user/:id. The comparison ignores case. Two users with the same value is ambiguous, and neither is used.
3. The provider's id as its own entity: "stripe_customer": "$.data.object.customer". The event is stored and can be found, but no decision about your user reads it.

When a delivery's event has no entity at all, nothing from it is stored, and it waits in the log as No entity. Once the connection exists (the payment arrived, the property was set), Run failed again stores it.

Templates#

A template is a provider that Kairos already knows: its signature scheme, the steps at the provider, and a mapping written for its payloads. In the console, open Settings › Webhooks › Inbound webhooks, choose Add source › Start from a template, and pick one. The list is grouped by what the provider does:

Each template shows its setup steps when you choose it. The URL to give the provider is shown once, after you add the source.

A template is a starting point. The templates are written from each provider's documentation and its example payloads. Until a real delivery from the provider has gone through one, the console says, when you choose it, that it has not yet been checked with a real delivery. After the first deliveries arrive, open them in the delivery log, and change the mapping if a field you need is missing or named differently in your account (providers change payloads by API version).

The template is a copy: you can change the source's mapping, and a newer version of the template does not change your source.

Connect Stripe#

In the console, open Settings › Webhooks › Inbound webhooks and choose Add source › Start from a template › Stripe.

1. Paste the endpoint's signing secret (whsec_…) and add the source. Kairos shows the source's URL once. Copy it.
2. In Stripe, open Developers › Webhooks and add an endpoint with that URL. Select these events: payment_intent.succeeded, payment_intent.payment_failed, payment_intent.processing, payment_intent.canceled, charge.refunded, charge.dispute.created, charge.dispute.closed.
3. Put your user id in the metadata of each PaymentIntent you create: metadata: { user_id: "user_42" }.

What each Stripe event becomes:

All of them are stages of one record: the PaymentIntent (GET /v1/records/pi_…). Refunds and disputes find their user from it (way 2 above). Amounts are in minor units, as Stripe sends them: amount_minor: 9500 is $95.00. Kairos does not divide by 100, because that is wrong for a currency with no minor unit, such as JPY.

Connect another provider#

Choose Add source › Start from scratch. Give the source a name, choose how deliveries are signed (Verification), and paste the signing secret. The source starts with a simple mapping. On its page:

1. Paste a sample payload from the provider's documentation, or take one from a recent delivery. A delivery from the log comes with its headers (without the signature). For a mapping that reads or matches a header, put the headers in Request headers.
2. Change the rules. Click a value in the sample to put its path in the field you used last.
3. The Result on the sample shows what the server would store, exactly: the same engine runs in the browser and on the server.
4. Save mapping. Deliveries that failed before can then run again.

Edit as JSON shows the whole mapping, for what the form does not show (a lookup table on a value, set, properties.all), or to copy a mapping between sources.

The mapping#

A mapping is a list of rules. Every delivery is tried against every rule, in order. Each rule that matches runs, so one delivery can make several events.

{
  "rules": [
    {
      "name": "Payment",
      "match": { "type": ["payment.succeeded", "payment.failed"] },
      "event": {
        "id": "$.id",
        "type": "payment",
        "ts": { "path": "$.created", "format": "unix_seconds" },
        "entities": { "user": "$.data.metadata.user_id" },
        "universal_id": "$.data.id",
        "status": { "path": "$.type", "values": { "payment.succeeded": "completed", "payment.failed": "failed" } },
        "properties": { "amount_minor": "$.data.amount", "currency": "$.data.currency" }
      }
    },
    {
      "name": "Dispute",
      "match": { "type": "dispute.created" },
      "event": { "id": "$.id", "type": "dispute_opened", "entities": { "user": { "record": "$.data.payment_id" } } },
      "label": { "entity": "user", "label": "chargeback" }
    }
  ],
  "unmatched": "ignore"
}

Values#

A value in a mapping is one of these:

Paths: $ is the payload; .name, ["a name"] and [0] go into it, and [-1] is the last element of a list. Inside items, $$ is the element. There are no wildcards and no filters. A path that finds nothing gives no value.

Transforms, on { "path": … }:

A rule#

When a rule that matched fails (no id, a time that cannot be read, no entity), nothing from that delivery is stored. Correct the mapping and run it again: the whole delivery then goes in at once.

Verification#

A provider cannot send your API key. A delivery is accepted on two things: the secret token in its URL, and the provider's signature over the body.

• The signature is checked on the raw bytes of the body, in constant time.
• A source can hold two secrets while a provider rotates: Add second, then Replace when the provider uses only the new one.
• The secret is stored encrypted, because Kairos must use it to compute the signature.
• New URL makes a new token and stops the old URL at once, for a URL that leaked.

What Kairos answers, and the delivery log#

Kairos answers after the events are stored. Once a delivery is verified and read, it answers 200, even when the mapping fails:

A mapping problem answers 200 on purpose: the provider's retry would send the same payload to the same mapping, and many providers turn off an endpoint that fails too often. Correct the mapping and use Run failed again (failed and no-entity deliveries) or Run again on one delivery. A replay uses the same event ids, so what was stored already is not stored twice.

The log keeps each delivery, without the signature headers. The payload is kept 7 days and then removed; the row stays. A rejected delivery keeps no payload: it did not prove where it came from.

A new label from a webhook, such as a chargeback, also goes to your outbound webhooks as label.created.

Limits and security#

• A source can write events and labels, and nothing else. It cannot read, decide, or change a definition.
• The URL token is a secret. It appears in the access logs of proxies, which is why a signature scheme is better than none.
• Only owners and admins can see and change sources. The token is shown once; secrets are never shown again, only a hint.

The API#

The console does all of this. The same calls, for a script (a session cookie and the admin role, under /app/workspaces/:workspace):

# The presets (a secret key or a session)
curl -s https://kairos.finic.ai/v1/webhook-presets -H "Authorization: Bearer $KAIROS_API_KEY"

The engine is also in @kairos/core: applyMapping(mapping, { body, headers }, receivedAt) and validateMapping(mapping), for a test of your own mapping.