Agency webhooks

Rather than polling, register an endpoint and DMLY will POST to it whenever one of your sub-accounts changes: a workspace is created, suspended or restored, or a subscription or add-on changes. These are agency webhooks, separate from the workspace webhooks that fire on activity inside a workspace.

The events

There are six:

Event	Fires when
`workspace.created`	A customer signs up on your branded domain, or you create a sub-account with `POST /workspaces`
`workspace.suspended`	A sub-account is suspended
`workspace.restored`	A suspended sub-account is restored
`subscription.changed`	A sub-account’s base plan changes
`addon.granted`	An add-on is granted to a sub-account
`addon.revoked`	An add-on is revoked from a sub-account

The suspend, restore, plan and add-on events fire whether the change was made in the agency console or over the Agency API, so one subscription keeps you in sync with both. workspace.created is the exception: the console has no create button, so it fires only from a branded sign-up or from the API.

workspace.created fires only for a brand-new sub-account created by a branded sign-up or by POST /workspaces. Two other ways a workspace can join your agency do not fire it: an existing customer adding a second workspace from the workspace switcher, and your own workspace being moved under your agency when you took a reseller plan. Both appear in your sub-accounts list without a webhook, so if you must catch every workspace, reconcile periodically against GET /workspaces. Client workspaces covers all three arrival paths.

Setting one up

You can manage webhook endpoints from the agency console, under Reseller Dashboard → Webhooks, or over the API with the /webhooks endpoints in the sidebar. In the console each endpoint’s row carries Test, Rotate secret, Edit and Remove.

In the console, select + Add webhook. Add your endpoint URL (it must be publicly reachable over HTTPS) and subscribe to the events you care about.

Store the signing secret

A signing secret is generated for you and returned once, on creation. Store it; you use it to verify every delivery. If you lose it, select Rotate secret on the endpoint’s row to get a new one, which invalidates the old one.

Send a test

Use the test event to confirm your endpoint is reachable and your signature check works before relying on it. In the reseller dashboard, select Test on the endpoint’s row. A test payload carries an extra "test": true.

The payload

Every delivery has the same envelope. Only data varies by event:

{
  "id": "9f1c4b6e-3a2d-4f8b-9c1e-2a7d5e8b0c31",
  "event": "workspace.created",
  "occurred_at": "2026-07-14T09:30:00+00:00",
  "agency_id": 7,
  "data": {
    "workspace": {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "name": "Acme Fitness",
      "status": "active",
      "plan": { "uuid": "22222222-2222-2222-2222-222222222222", "name": "Starter" }
    }
  }
}

The subscription.changed payload adds the new plan; addon.granted and addon.revoked add an addon object. Each event page in the sidebar shows its exact payload.

Headers

Header	Value
`X-Dmly-Event`	The event, e.g. `workspace.created`
`X-Dmly-Delivery`	Id for this delivery: the envelope `id`, stable across retries
`X-Dmly-Signature`	`sha256=<hmac>`, sent whenever the endpoint has a signing secret
`User-Agent`	`Dmly-Agency-Webhooks/1.0`

Verifying a delivery

The signature is an HMAC-SHA256 of the raw request body, keyed by your endpoint’s secret. Compute it over the bytes exactly as received; parsing and re-serialising the JSON first changes the bytes, and the signature will never match.

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Always compare with a constant-time function (hmac.compare_digest, crypto.timingSafeEqual). A plain == leaks timing information that can be used to forge a signature.

Responding

Return any 2xx to acknowledge. A non-2xx (or a timeout) is treated as a failure and retried twice more, after roughly 10s then 60s (three attempts in total). After the third the delivery is marked failed and not retried again. Nothing is lost silently: every attempt is recorded. In the reseller dashboard, open Webhooks and look under Recent deliveries, which lists the last 30 deliveries across all your endpoints with columns Webhook, Event, Result and When. Result shows the outcome and the HTTP status your endpoint returned, for example error · 500. The section only appears once there has been at least one delivery. Each endpoint’s row also shows its most recent outcome inline, as last: success or last: error. One case is never retried. DMLY re-checks your endpoint’s host at delivery time, because DNS can change between saving the endpoint and sending to it. If that check fails, nothing is sent: the delivery shows in Recent deliveries as an error with no HTTP status, and no further attempt is made.

Deliveries are at-least-once: a timeout on your side can produce a retry for an event you already handled. Deduplicate on the envelope’s id (the same value as the X-Dmly-Delivery header), which is stable across retries.

Events

Each event is documented with its full payload in the sidebar under this section; the list is generated from the API itself, so it is never out of date.

Getting started

Endpoints

Webhook events

Agency webhooks

The events

Setting one up

The payload

Headers

Verifying a delivery

Responding

Events

​The events

​Setting one up

​The payload

​Headers

​Verifying a delivery

​Responding

​Events

The events

Setting one up

The payload

Headers

Verifying a delivery

Responding

Events