Webhooks

Webhooks let your integration react to changes in Smarty.tel in real time, instead of polling the Resource API.

Creating a webhook

Webhooks are configured as Webhook documents, either from the Smarty.tel admin UI or through the API itself:

curl -X POST "https://app.smarty.tel/api/resource/Webhook" \
  -H "Authorization: token <api_key>:<api_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_doctype": "Ticket",
    "webhook_docevent": "on_update",
    "request_url": "https://your-service.example.com/hooks/smarty",
    "request_method": "POST",
    "enabled": 1,
    "webhook_headers": [
      {"key": "X-Source", "value": "smarty-webhook"}
    ],
    "webhook_data": [
      {"fieldname": "name"},
      {"fieldname": "status"},
      {"fieldname": "priority"}
    ]
  }'

Supported doc events

Event	Fires when
after_insert	A new document is created.
on_update	An existing document is saved.
on_submit	A submittable document is submitted.
on_cancel	A submittable document is cancelled.
on_trash	A document is deleted.

Payload shape

Your endpoint receives an HTTP POST with a JSON body containing the fields listed in webhook_data (or the full document if none are specified):

{
  "name": "TICK-2026-00042",
  "status": "Resolved",
  "priority": "High"
}

Verifying webhook signatures

Every webhook request includes an X-Frappe-Webhook-Signature header, an HMAC-SHA256 signature of the raw request body, signed with the webhook's secret (shown once at creation time, and re-generatable from the webhook record).

import hmac
import hashlib
import base64

def verify_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    computed = base64.b64encode(
        hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(computed, signature)

Always verify the signature before trusting the payload, and respond with a 2xx status quickly — Smarty.tel retries failed deliveries (non-2xx responses or timeouts) with exponential backoff, up to a configured retry limit.

Debugging deliveries

Failed and successful webhook deliveries are logged and can be inspected via the Webhook Request Log doctype through the standard Resource API:

curl -G "https://app.smarty.tel/api/resource/Webhook Request Log" \
  -H "Authorization: token <api_key>:<api_secret>" \
  --data-urlencode 'filters=[["webhook","=","<webhook-name>"]]' \
  --data-urlencode 'order_by=creation desc'

Next: Errors & Rate Limits.