Configuring webhooks

Overview

Webhooks reverse the flow of information: instead of having your systems ask for changes at regular intervals, Kyvento reports events – new subscriptions, paid invoices, failed payments – immediately via HTTP POST to your URL. This article shows the setup, event selection and signature verification.

Creating an endpoint

Open Settings → "Webhooks" (the "Integration" group) and click "+ New endpoint":

• "Name (optional)": for example "ERP integration" – to recognize it in the list.
• "Endpoint URL": the HTTPS address of your receiver. Kyvento rejects private and internal network addresses for security reasons.
• "Authentication & headers (optional)": if needed, basic-auth credentials and your own HTTP headers, which Kyvento sends along with every delivery.
• "Events": the event types this endpoint should receive, via checkbox – or "Select all".

After creation, Kyvento shows the signing secret (prefix whsec_) only once – store it securely in your receiver application, you need it for signature verification.

The most important event groups

• customer.* – customer created, updated, deleted, payment method updated
• subscription.* – subscription created, renewed, paused, cancelled, trial converted or ending soon, plan changed
• invoice.* – invoice finalized, paid, partially paid, overdue, cancelled
• payment.* – payment succeeded, failed, refunded, direct debit returned
• dunning.* – dunning level escalated, dunning paused/resumed
• test.ping – for connection tests

Structure of a delivery

Every delivery is a JSON POST with a stable envelope: id (event ID), type, created, account_id, data.object (the affected object) and, for changes, previous_attributes. It comes with the headers X-Kyvento-Event (type), X-Kyvento-Delivery-Id (unique per delivery attempt) and the signature.

Verifying the signature (strongly recommended)

The header X-Kyvento-Signature has the form t=<timestamp>,v1=<signature>. The signature is an HMAC-SHA256 over the string timestamp.request-body with your signing secret as the key. Check both: signature correct and timestamp no older than 5 minutes – this way you reject forged and replayed deliveries.

Testing the connection

The "Send test" action immediately sends a sample event to your URL – ideal for checking reachability and processing before real events flow. Note: the test delivery serves the connection test and carries no signature – test your signature verification with a real event (such as test.ping via the API or an actual change).

Next steps

• Delivery retries and error diagnosis – see "Webhook retry and error handling"
• Interplay with the REST API – see "API documentation and examples"