# Guide to Clemta Webhooks: Features and Best Practices

Clemta lets partner platforms form and run US companies for their own customers through an API. Formation and compliance move through many slow steps, so Clemta's webhooks report each one: a company is incorporated, the IRS issues an EIN, a tax filing moves forward, a service order is quoted or completed, Clemta needs a document or signature from your customer, a file is published, or a compliance deadline is approaching. You relay those to your customer under your own brand.

## What are Clemta webhooks?

A Clemta webhook endpoint is registered on the Webhooks page of the partner dashboard. Each event is a JSON `POST` that names its `type` and carries the affected resource as `data.object`, in the same shape the API returns. Webhooks are the push side of `GET /events`: both read one event stream, so anything a webhook misses can be read back from the API, where events never expire.

Clemta signs to the Standard Webhooks specification and sends both of the signature schemes it defines on every delivery: a symmetric `v1` HMAC and an asymmetric `v1a` Ed25519 signature, in one space-separated header. It also sends each header twice, as `webhook-*` and as `Clemta-Webhook-*`, with identical values.

## Clemta webhook features

| Feature | Details |
| --- | --- |
| Configuration | Partner dashboard, **Webhooks** page |
| Filtering and versioning | Optional event-type restriction and API version pin per endpoint |
| Signature | Standard Webhooks HMAC-SHA256 (`v1`) plus Ed25519 (`v1a`) |
| Signature header | `webhook-signature`, also sent as `Clemta-Webhook-Signature` |
| Secret | Per endpoint, `whsec_...`, shown once at creation. Public key `whpk_...` readable on the endpoint |
| Rotation | Rolled from the dashboard with an emailed code, with an overlap period |
| Body | JSON |
| Event routing | Body field `type` |
| Retries | Up to 20, jittered exponential backoff, 15 seconds to 6 hours apart |
| Ordering | Best effort per endpoint, one delivery at a time |
| Auto-disable | `410 Gone`, or three days of continuous failure |
| Replay | `GET /events` |
| Source IPs | Not published |

## Events and payloads

Clemta lists 27 event types:

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `company.created` | A company you created was accepted | Store the company id |
| `company.status.changed` | A company moved between `in_progress`, `active` and `cancelled` | Update your customer's status; branch on status |
| `company.verified` | Every owner's identity document is in (once, before incorporation) | Tell the customer verification is done |
| `company.incorporated` | The state accepted the filing (once) | Mark the company as formed |
| `company.onboarding.completed` | A `pre_existing` company finished onboarding (once) | Counterpart of `company.incorporated` for companies formed elsewhere |
| `company.name.changed` | The legal name changed, typically to clear a state conflict | Refresh the stored name |
| `company.ein.assigned` | The IRS issued the EIN (once); payload carries `ein` | Store the EIN |
| `company.document.received` | An owner uploaded their identity document | Show progress |
| `company.entitlements.changed` | A tax-filing credit was added or consumed | Update remaining filings |
| `company.updated` | Entity type, state, name suffix, industry, shares, formation date, address or owners changed | Refresh the company record |
| `company.dissolved` | A dissolution order completed (once) | Close the account; renewals stop and open requirements close |
| `tax_filing.created` | A federal or state filing was opened (one right consumed) | Track the filing |
| `tax_filing.status.changed` | A filing's `status` or `progress` moved | Show filing progress |
| `service_order.status.changed` | An order was created or moved through fulfilment, including cancellation | Update the order; branch on status |
| `service_order.completed` | The order reached its final step; fires again if it reopens and completes once more | Deliver the result |
| `service_order.updated` | Options or price changed without your call (a reversed upgrade is credited back) | Refresh the order |
| `service_order.quoted` | A `quote_pending` order was priced | Accept before `quote.expires_at`; nothing bills until you do |
| `service_order.renewal_canceled` | Your renewal-cancellation request was approved | Show the `renewal_ends_at` date |
| `service_order.renewal_cancel_denied` | Your renewal-cancellation request was denied | Tell the customer it keeps renewing |
| `requirement.created` | Something is needed from you or your customer | Prompt the customer |
| `requirement.fulfilled` | A requirement was resolved; payload carries its response | Clear the task |
| `requirement.canceled` | An open requirement closed unfulfilled (declined signature, withdrawn ask); `cancel_reason` says why | Clear or escalate the task |
| `requirement.signature.viewed` | A signer opened a signature document (once per signer) | Progress only |
| `requirement.signature.signed` | A signer signed (once per signer) | Progress; `requirement.fulfilled` follows when the last signs |
| `file.created` | A document was published on one of your companies | Download it from the file's content endpoint |
| `calendar.reminder` | A compliance deadline is approaching (once per reminder point); payload has `due_at` and `remind_at` | Relay under your own brand; Clemta sends no mail to your customer |
| `invoice.finalized` | A month-end invoice was issued | Reconcile billing |

`data.object` has its own `object` field naming the resource kind, such as `company`, `tax_filing`, `service_order`, `requirement`, `file` or `invoice`. The event ID is the `webhook-id` header, which stays the same across retries.

Clemta doesn't publish example delivery bodies; the per-event reference pages show schemas. Test companies never advance on their own. In test mode, `POST /sandbox/companies/{id}/simulate` drives them forward, which triggers formation events with real payloads.

## Setting up Clemta webhooks

1. Open the **Webhooks** page in the partner dashboard and create an endpoint with your HTTPS URL.
2. Optionally restrict it to the event types you handle and pin it to an API version, so payload shapes don't change under you.
3. Copy the signing secret straight away. It is shown once. Store it as `CLEMTA_WEBHOOK_SECRET`.

Use a `clmt_test_` key while developing; it never touches live data.

To send Clemta's events through Hookdeck, create a source with the **Clemta** type, paste the `whsec_` secret, and register the source URL as the endpoint. You can then forward test traffic to your machine with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 clemta --path /webhooks/clemta

```

To rotate, roll the secret on the Webhooks page and confirm with the one-time code Clemta emails you. During the overlap, deliveries carry two `v1,` entries, one per secret, and either verifies. Update your receiver or Hookdeck source within that window.

## Securing Clemta webhooks

For the HMAC path, sign `<webhook-id>.<webhook-timestamp>.<raw body>` with the base64-decoded secret after `whsec_` and compare against each `v1,` entry in `webhook-signature`. Skip `v1a,` entries: they are Ed25519 signatures over the same string and need the `whpk_` public key instead. The function below does exactly that:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

Clemta's sample verifier defaults to a 300-second tolerance, and Clemta re-signs each retry with a fresh timestamp, so its own retries pass. A replay or retry from Hookdeck is different: Hookdeck keeps the timestamp Clemta sent and applies no tolerance of its own. Keep any age check you add wider than your Hookdeck retry window, or leave it out as above.

The receiver below stores the event under its `webhook-id` and returns `2xx`. A `3xx` counts as a failure, so the route must answer directly:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

// events.save(webhookId, event) stores the event and resolves once it is durable.
function createClemtaReceiver(events) {
  const app = express();
  app.post('/webhooks/clemta', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.CLEMTA_WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    const event = parseJsonObject(req.body);
    if (!event) return res.sendStatus(400); // signed, but not a JSON object
    try {
      await events.save(req.headers['webhook-id'], event);
    } catch {
      return res.status(503).set('Retry-After', '60').end(); // Clemta honours Retry-After
    }
    return res.sendStatus(200);
  });
  return app;
}

```

A Hookdeck Clemta source reads the `webhook-*` headers and checks the `v1` HMAC. It returns `200` to Clemta in every case and records a signature mismatch as failed verification instead of forwarding the request.

> **Make Clemta webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies the HMAC on every formation, filing and compliance event, keeps each one searchable, and routes customer-facing events and billing events to different services.

## Clemta webhook limitations and pain points

### The secret is shown once

**The Problem:** You lose the secret and can't verify deliveries.

**Why It Happens:** Clemta shows the `whsec_` value only when the endpoint is created.

**Workarounds:**

* Store it in your secrets manager before closing the dialog.
* If it's lost, roll the secret from the dashboard and use the overlap to deploy the new one.

**How Hookdeck Can Help:** With a Hookdeck source in front, the secret lives in one place, and you can update it there during the overlap without redeploying services.

### Endpoints get disabled

**The Problem:** After a long outage or a stray `410`, Clemta stops sending to your endpoint.

**Why It Happens:** An endpoint that fails continuously for three days is disabled automatically, and a `410 Gone` disables it at once.

**Workarounds:**

* Never return `410` from a webhook route.
* Re-enable the endpoint in the dashboard; queued deliveries resume.
* Read missed events from `GET /events`.

**How Hookdeck Can Help:** Hookdeck always answers Clemta with `200`, so your service's errors and downtime never count towards Clemta's three-day limit, and Hookdeck [retries](/docs/retries) delivery to you until it succeeds.

### Order is best effort

**The Problem:** `tax_filing.status.changed` events arrive out of sequence and an older status overwrites a newer one.

**Why It Happens:** Clemta delivers one event at a time per endpoint, in order, but sets aside an event that keeps failing so the queue can move on. Its docs say to treat order as normal, not guaranteed.

**Workarounds:**

* Compare the status or `progress` in `data.object` with what you hold, and fetch the resource from the API when in doubt.
* Deduplicate on `webhook-id`.

**How Hookdeck Can Help:** Hookdeck's event history shows the order in which deliveries actually arrived, which helps when you investigate a status that went backwards.

### No example bodies

**The Problem:** You write parsers against schemas and find surprises in production.

**Why It Happens:** Clemta's webhooks page doesn't print delivery bodies, and the reference pages show schemas only.

**Workarounds:**

* Use test mode and the sandbox simulate endpoint to generate real events before go-live.

**How Hookdeck Can Help:** Every request to a Hookdeck source is stored in full, so sandbox deliveries become a library of real examples.

## Best practices

### Relay reminders yourself

`calendar.reminder` carries `due_at` and `remind_at`. Clemta sends no mail to your customer, so the deadline only reaches them if you pass it on.

### Accept quotes in time

`service_order.quoted` means a `quote_pending` order has a price. Nothing is billed until you accept it, and the quote has an expiry in `quote.expires_at`.

### Pin an API version

Pin each endpoint to the API version your code expects. Otherwise payloads render at the workspace webhook version, which can change when someone updates it.

### Close tasks on requirement events

`requirement.created` asks for something from you or your customer. Clear your task on `requirement.fulfilled` or `requirement.canceled`, and read `cancel_reason` on the latter.

### Deduplicate on `webhook-id`

It is the event ID and survives retries. Key on it as the [idempotency guide](/webhooks/guides/implement-webhook-idempotency) describes.

## Conclusion

Clemta's webhook design is thorough, with versioned payloads, two signatures and an event API you can catch up from. Most of the effort goes into relaying its 27 event types, especially deadlines and requests, to your customers.

[Hookdeck Event Gateway](https://hookdeck.com) adds routing per event family and a full delivery history in front of your Clemta endpoint. [Try it with a free account](https://dashboard.hookdeck.com/signup).