Webhooks integration

Webhooks send what happens in Kirora to your own systems: a contact unsubscribing, a form being submitted, an email bouncing. Point them at a public HTTPS endpoint you control, choose the events, and each delivery arrives signed so you know it came from Kirora.

Before you start

• Maintained by: Kirora.
• Availability: built in to Kirora, with nothing to install.
• Direction: out of Kirora, to your endpoint.
• You need: an HTTPS endpoint you control that can read each request’s raw body, and either Developer › Webhooks in Kirora or an API key with the webhooks:write scope.

Events you can subscribe to

• Contacts: contact.created, contact.unsubscribed, contact.consent_changed
• Forms: form.submitted
• Campaigns and journeys: campaign.sent, journey.enrolled
• Messages: message.sent, message.delivered, message.opened, message.clicked, message.bounced, message.complained, message.failed, message.skipped

Subscribe to * to receive every event, including ones added later.

Contacts and consent

Each event carries the record as it was when it happened. Contact, form and journey events include the contact as the API returns it, with your external ID, so you can match it in your own systems; message events carry the contactId. contact.unsubscribed and contact.consent_changed tell you when someone’s consent changes. A message event never carries the message’s content.

Connect a webhook

1. In Kirora, open Developer › Webhooks, or use the API with a key that has the webhooks:write scope.
2. Add your endpoint’s HTTPS URL and choose its events. Copy the signing secret, which starts with whsec_.
3. In your endpoint, check each delivery’s signature, then return a 2xx quickly and do the work afterwards. Return a 2xx for event types you don’t handle too, so new ones never cause retries.

Test it

1. On Developer › Webhooks, choose Send test event for your endpoint. Over the API, it’s POST /v1/webhooks/{id}/test. The webhook must be active.
2. Your endpoint receives a webhook.test delivery, signed like any other. Check that your code verifies its signature and returns a 2xx.
3. The delivery appears under Recent deliveries, with your endpoint’s response.

How deliveries work

• Signed: X-Webhook-Signature is sha256= followed by an HMAC-SHA256 of the timestamp and the raw body, keyed with your signing secret. The timestamp is in X-Webhook-Timestamp.
• Safe to retry: X-Webhook-Event-Id stays the same across retries, so you can skip an event you’ve already handled. X-Webhook-Attempt says which attempt it is.
• Retried: a failed delivery is tried again with growing gaps, over about 45 hours. A 410 Gone response turns the webhook off at once.

Use it for

• Your CRM in step: mark a contact as unsubscribed in your own systems when they opt out.
• Leads where your team works: send each form submission to your sales tools.
• Delivery data in your warehouse: store sends, opens, clicks and bounces next to the rest of your data.

Limitations

• Your endpoint has 5 seconds to answer, so acknowledge first and do the work afterwards.
• Redirects aren’t followed: use the endpoint’s final URL.
• Each URL can have one subscription in a workspace.
• Delivery is at least once and not always in order: a message.delivered can arrive before its message.sent. Skip events you’ve handled by X-Webhook-Event-Id, and order them by the timestamps in each event.

Get help

Recent deliveries on Developer › Webhooks shows each delivery with your endpoint’s response, or why it failed, and Send again resends a failed one. The webhooks guide has every payload. For anything else, contact us.

Questions

Which plans include webhooks?

Every plan, Free included.

What happens while a webhook is paused?

It receives no new events, and events that happen meanwhile aren’t kept for it. Deliveries that were already waiting are sent once you turn it back on. The same applies when Kirora turns a failing webhook off. To catch up, read what changed in that time through the API.

What does message.delivered mean?

The recipient’s mail server accepted the email. It doesn’t say whether it reached the inbox or the spam folder, and push messages don’t have it. message.opened fires on the first open, which can come from a mail app’s privacy feature rather than the person.

Next steps

• Webhooks guide: every event’s payload, and code to check signatures.
• Zapier, Make and n8n: use these events in your automations. Kirora’s native apps are coming soon; each page shows the web request route available today.