Add a new webhook definition

POST

/v2/webhooks/payments

const url = 'https://sender.api.kivra.com/v2/webhooks/payments';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"url":"example","cid_filter":"example","tkey_filter":"example","types":["instant"],"events":["scheduled"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://sender.api.kivra.com/v2/webhooks/payments \
  --header 'Content-Type: application/json' \
  --data '{ "url": "example", "cid_filter": "example", "tkey_filter": "example", "types": [ "instant" ], "events": [ "scheduled" ] }'

Create a payment webhook definition with filters.

Request Body

application/json

object

url

The URL to which Kivra will try to deliver the webhook payloads. Must not be in a reserved domain, must have at least one IPv4 address and must not have any IPv4 addresses in a reserved range. The URL scheme must be HTTPS.

string format: url

cid_filter

The client key of the party that made the API call to send the invoice the payment was based on to Kivra.

string

tkey_filter

The tenant key of the sender of the invoice the payment was based on.

string

types

A list of the types of payments that the tenant wants to receive webhooks for.

Array<string>

Allowed values: instant bank autogiro

events

A list of the payment lifecycle events that the tenant wants to receive webhooks for.

Array<string>

Allowed values: scheduled settled failed declined

Responses

201

The definition of the just-created webhook.

application/json

PaymentWebhookDefinition

A definition used to send webhooks from Kivra to a sender.

object

The ID of the current webhook definition.

string format: uuid

url

The target URL that Kivra will try to deliver to. The hostname in the URL must not be in a restricted domain (like for example example.org or local). The hostname also must resolve to at least one IPv4 address, and must not resolve to any addresses in an IPv4 range reserved by IANA.

string format: url

cid_filter

The client key filter for this webhook configuration.

string

/^[0-9]{10}[a-f0-9]{32}$/

tkey_filter

The tenant key filter for this webhook cofiguration.

string

/^[0-9]{10}[a-f0-9]{32}$/

types

A list of the types of payments that should trigger webhooks.

Array<string>

Allowed values: instant bank autogiro

events

A list of the payment events that should trigger webhooks. Not all events are meaningful for all payment types.

Array<string>

Allowed values: scheduled settled failed declined

secret

The newly created secret after a webhook definition was added or modified. The secret is a 256-bit random number that will be used to sign webhook payloads from Kivra. If a secret already exists when a new one is added (that is, when a webhook definition is modified rather han created), payloads will be signed with both the existing and the new secrets for the next 72 hours. For security reasons, this field will be missing in reponses to API calls that do not result in the creation of a new secret.

string format: base64

created_at

The time when this definition was created.

string format: date-time

Example

{
  "types": [
    "instant"
  ],
  "events": [
    "scheduled"
  ]
}