Skip to content

Developer docs

Webhooks

DevEntitle POSTs a signed JSON event to your URL the moment something happens: a licence issued, a site activated, a release published, an order paid.

Also in the app: terminal.deventitle.com/docs/webhooks · Machine-readable spec: openapi.json (OpenAPI 3.1)

Adding an endpoint

Add endpoints in the panel under Developers → Webhooks, or with POST /webhook-endpoints. Each endpoint has its own signing secret (whsec_…), shown once.

URLs must be HTTPS on a public address. Private and internal addresses are refused, checked again at send time, and redirects are not followed.

Events

EventWhen
license.createdA licence was issued (panel, API, connected app or checkout)
license.updatedSupport extended, limit changed, suspended or reinstated, notes changed
license.revokedA licence was revoked or refunded
activation.createdA product activated a licence on a new site or device
activation.removedA site or device was removed from a licence
release.publishedA release was published
order.paidA storefront order was paid (licence issued or renewed)
order.refundedAn order was refunded, in full or in part

Subscribe to * to receive new event types automatically. A paid storefront order sends order.paid and, for a new licence, license.created too.

Licence keys are never included

Payloads carry a key_hint (the last five characters, such as …C8ZVD), never the key itself.

Payload and headers

An event delivery
POST /your/endpoint
Content-Type: application/json
DevEntitle-Event: license.created
DevEntitle-Delivery: 5f0d6b0e-…        (the event id)
DevEntitle-Signature: t=1793390000,v1=6a1f…

{
  "id": "5f0d6b0e-…",
  "type": "license.created",
  "created_at": "2026-11-01T09:30:00Z",
  "vendor": {"id": 42, "slug": "acme-software"},
  "data": {"license": {"id": 901, "key_hint": "…C8ZVD", "status": "active", …}}
}

Objects in data have the same shape as in the Management API.

Checking the signature

v1 is the hex HMAC-SHA256 of "<t>.<raw body>" using the endpoint’s signing secret. Reject the delivery if it doesn’t match, or if t is more than 5 minutes old. Always compute it over the raw body, before parsing JSON.

PHP
$body = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([0-9a-f]+)/', $_SERVER['HTTP_DEVENTITLE_SIGNATURE'] ?? '', $m);
$valid = $m
    && abs(time() - (int) $m[1]) < 300
    && hash_equals(hash_hmac('sha256', $m[1].'.'.$body, getenv('DEVENTITLE_WEBHOOK_SECRET')), $m[2]);
Node.js
// Express: use express.raw() for this route
import { createHmac, timingSafeEqual } from 'node:crypto';
const [, t, v1] = req.get('DevEntitle-Signature').match(/t=(\d+),v1=([0-9a-f]+)/) ?? [];
const expected = createHmac('sha256', process.env.DEVENTITLE_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest('hex');
const valid = v1 && Math.abs(Date.now() / 1000 - t) < 300 && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
Python
import hmac, hashlib, re, time

def valid_signature(header: str, body: bytes, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]+)", header or "")
    if not m or abs(time.time() - int(m[1])) >= 300:
        return False
    expected = hmac.new(secret.encode(), m[1].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, m[2])

Delivery and retries

  • Answer with any 2xx within 10 seconds. Do slow work after answering.
  • Otherwise the delivery is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h: 8 attempts in about two days, then it is marked failed.
  • Events can arrive more than once. Use the event id (DevEntitle-Delivery) to ignore duplicates.
  • Order isn’t guaranteed. Use created_at, or fetch the current state from the API.

Logs, tests and secrets

  • Every delivery, response and error is listed on the endpoint’s page for 90 days.
  • Send test event sends a ping.
  • Redeliver resends any delivery.
  • The signing secret can be rotated.