Add a new webhook definition

This endpoint is used to add a new webhook definition.

A partner is allowed to define more than one webhook. It's up to the partner themselves to make sure not to create duplicate definitions. If they do, they will receive duplicate webhooks for the same payments.

A webhook definition essentially consists of a destination URL, and four fields defining a filter for which payments should be reported on. The fields are:

• cid_filter: The client id of the partner who sent the invoice the payment was based on to Kivra. Can be a key or the special value *, which means all keys. This value is not possible to set via this API, since it would allow leaking information between partners. If you need to receive webhooks for payments based on invoices sent by another partner, contact Kivra.

• tkey_filter: The tenant key for the actual sender of the invoice the payment was based on. This may be the same entity as the sending client, but very often is not. This key may also be set to the special value *, in which case webhooks will be delivered for all invoiced sent by the given client id, no matter which tenant they were sent on behalf of. It is never allowed for both this key and cid_filter to be set to *, since that would mean reporting on absolutely every payment made through Kivra.

• types: A list consisting with strings representing the types of payments webhooks should be delivered for. Currently available are instant (Swish), bank and autogiro.

• events: A list of the events concerning a payment that a webhook should be delivered for. Currently available are scheduled, settled, failed and declined.

Not all events apply to all types. Currently, the exhaustive list of events for each type is:

• instant_payment_settled
• instant_payment_failed
• bank_payment_settled
• bank_payment_scheduled
• bank_payment_failed
• autogiro_payment_settled
• autogiro_payment_scheduled
• autogiro_payment_failed
• invoice_declined

invoice_declined is a special event which currently only applies to content with the type invoice.renewal or invoice.donation. Regular invoices, i.e. with type invoice, can not be declined in Kivra.

The receiving system must respond to Kivra's POST request with a 2xx HTTP response code, and the response must come within one second of the connection being established.

If the POST request is not successfully delivered, Kivra will retry up to ten times at increasing intervals following the recommended timetable from Standard Webhooks. If the delivery still has not succeeded when those attempts are down, the delivery attempt will be discarded.