Webhooks

Yuva sends your backend a signed HTTP request when something happens, so you can send pushes, sync contacts or automate. Requests follow Standard Webhooks.

Add an endpoint

In the panel: Settings → Webhooks. Or with an API key that holds webhooks:manage:

curl -X POST https://support.example.com/v1/webhooks \
  -H "Authorization: Bearer $YUVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://api.example.com/yuva/webhook", "events": ["message.created"]}'

Save the signing secret (whsec_…) from the answer; it is shown once.

Verify the signature

Check every request on its raw body, before parsing. In Go:

import "github.com/productdevbook/yuva/sdk/go/webhook"

err := webhook.Verify(os.Getenv("YUVA_WEBHOOK_SECRET"), r.Header, body, 5*time.Minute)

Any Standard Webhooks library works too.

Answer quickly

Answer 2xx within 10 seconds. Failures are retried for about 24 hours. A delivery can arrive twice or out of order: skip a webhook-id you have handled and order by timestamp.

Reference

Events

Type	When	data
conversation.created	A conversation started, feedback included	conversation, contact
conversation.updated	Status, assignee, priority, labels, subject or spam flag changed, or it moved	conversation, contact
conversation.rated	The contact rated it (conversation.rating)	conversation, contact
message.created	A message from or to the contact; notes if enabled	message, conversation, contact
feedback.created	Feedback from an app or POST /v1/feedback	message, conversation, contact
contact.updated	A contact changed	contact
contact.deleted	A contact was deleted, or merged (merged_into_id)	contact
draft.created, draft.updated, draft.deleted	A draft changed; sending it emits message.created	message, conversation, contact
discussion.created	A discussion thread was started, also while it waits for a member (state: pending)	discussion
discussion.post_created	A reply was written in a thread, also while it waits for a member	discussion, post
discussion.answered	A reply was accepted as the answer	discussion, post
discussion.updated	A thread or post was approved, hidden, marked spam, edited, deleted, locked or unlocked, or the answer was cleared	discussion, and post when a post changed
subscription.created	Someone subscribed to a list of the endpoint’s inbox, in any state (pending while waiting for confirmation)	subscription, list, contact
subscription.updated	A subscription was confirmed, unsubscribed (with unsubscribe_reason) or subscribed again	subscription, list, contact, previous_state
analytics.alert	A website of Analytics raised an alert: spike, drop, goal drop, support load or new referrer	alert, property
broadcast.updated	A broadcast changed state: scheduled, sending, paused, sent, cancelled, failed or back to draft, or its pace changed	broadcast, previous_state
status.component.updated	A status page component was created, changed or got a new state	component, page, previous_state
status.incident.created, status.incident.updated, status.incident.resolved	A published incident or maintenance was published, changed, or resolved or completed	incident, page, change, update
status.monitor.down, status.monitor.up	A monitor failed or recovered	monitor, page, incident_id

Every body has type, timestamp (when it happened), workspace_id, inbox_id (not on contact events) and data. data.contact.online is false when the contact has no live connection: the moment for a push. Full schemas are in the webhooks section of openapi.yaml.

Endpoint fields

Field	Meaning
url	Public http or https. Private and reserved addresses are refused unless YUVA_WEBHOOK_ALLOW_PRIVATE is set (Configuration).
events	Event types to send.
inbox_id	Only this inbox; without it, the whole workspace.
include_notes	Also send members’ notes. Off by default.

Signature

Header	Meaning
webhook-id	Same on every retry.
webhook-timestamp	Unix seconds. Refuse values a few minutes off.
webhook-signature	v1, + base64(HMAC-SHA256(key, "<id>.<timestamp>.<raw body>")), key being the base64-decoded secret after whsec_. Two, space-separated, during a rotation.

Delivery

Rule	Detail
Retries	After 5 s, 1 min, 5 min, 30 min, 1 h, 2 h, 4 h, 8 h, 9 h, plus up to 10%. Redirects count as failures.
Disabled	After 24 hours of failures, or a 410 Gone. Enable it again in the panel.
Rotate secret	POST /v1/webhooks/{webhookId}/secret; the old one keeps signing for 24 hours.
Log	Last 100 attempts: GET /v1/webhooks/{webhookId}/deliveries, GET /v1/webhooks/{webhookId}/attempts.
Redeliver	POST /v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver.