For developers

Webhooks to your systems

Wavely sends your system an HTTP POST webhook each time something changes in a business your app owns.

Events you can receive

A webhook sends news to your system as an HTTP POST each time something changes in a business your app owns. There are 33 event types:

  • contacts: contact.created, contact.updated, contact.deleted, contact.opted_out, contact.opted_in
  • companies: company.created, company.updated, company.deleted
  • conversations: conversation.created, conversation.closed
  • messages: message.created, message.status_updated, message.edited, message.deleted
  • channels: channel.updated
  • teams: division.created, division.updated, division.deleted, division.members_updated
  • agents: agent.created, agent.updated, agent.deleted
  • branches: branch.created, branch.updated, branch.deleted
  • products: product.created, product.updated, product.deleted
  • quotations: quotation.created, quotation.sent, quotation.accepted
  • business: organization.updated, organization.deleted

Every delivery carries id, type, version, timestamp, organization_id and data.

Register an endpoint

You need a secret key with the webhooks:manage scope. Webhook routes do not use the Wavely-Organization header.

curl -X POST https://WAVELY-HOST/platform/v1/webhook-endpoints \
  -H "Authorization: Bearer wvsk_..." \
  -H "Idempotency-Key: 6f1c0d52-0b0e-4c7e-9d1a-3c2a1f6b7e10" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://app.example.com/wavely","event_types":["message.created","conversation.closed"]}'

An empty event_types means every type. The URL must point to a public address. Each app may have up to 20 endpoints. To read the signing secret, call GET /webhook-endpoints/{id}/secret. Call POST /webhook-endpoints/{id}/test to send a webhook.test event.

Check the signature

Wavely signs every delivery following the Standard Webhooks scheme. The headers webhook-id, webhook-timestamp and webhook-signature come with each delivery. The key is the base64-decoded bytes of the whsec_... secret. The signature is an HMAC-SHA256 of id.timestamp.body, written as v1, followed by the base64 signature.

import base64, hashlib, hmac

def valid(secret, msg_id, ts, body, header):
    raw = secret.removeprefix("whsec_")
    key = base64.b64decode(raw + "=" * (-len(raw) % 4))
    signed = f"{msg_id}.{ts}.".encode() + body
    mac = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(mac, p[3:]) for p in header.split() if p.startswith("v1,"))

Answer with a 2xx status to mark success. Delivery is at least once and order is not guaranteed, so store the webhook-id and ignore ones you already handled. A failed delivery is retried up to ten times over about three days. An endpoint that keeps failing for 72 hours is disabled automatically. After you fix it, you can retry one delivery or replay events from a time window.