Gareth Wilson Gareth Wilson

Guide to Clemta Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationPartner dashboard, Webhooks page
Filtering and versioningOptional event-type restriction and API version pin per endpoint
SignatureStandard Webhooks HMAC-SHA256 (v1) plus Ed25519 (v1a)
Signature headerwebhook-signature, also sent as Clemta-Webhook-Signature
SecretPer endpoint, whsec_..., shown once at creation. Public key whpk_... readable on the endpoint
RotationRolled from the dashboard with an emailed code, with an overlap period
BodyJSON
Event routingBody field type
RetriesUp to 20, jittered exponential backoff, 15 seconds to 6 hours apart
OrderingBest effort per endpoint, one delivery at a time
Auto-disable410 Gone, or three days of continuous failure
ReplayGET /events
Source IPsNot published

Events and payloads

Clemta lists 27 event types:

EventTriggered WhenCommon Use Cases
company.createdA company you created was acceptedStore the company id
company.status.changedA company moved between in_progress, active and cancelledUpdate your customer's status; branch on status
company.verifiedEvery owner's identity document is in (once, before incorporation)Tell the customer verification is done
company.incorporatedThe state accepted the filing (once)Mark the company as formed
company.onboarding.completedA pre_existing company finished onboarding (once)Counterpart of company.incorporated for companies formed elsewhere
company.name.changedThe legal name changed, typically to clear a state conflictRefresh the stored name
company.ein.assignedThe IRS issued the EIN (once); payload carries einStore the EIN
company.document.receivedAn owner uploaded their identity documentShow progress
company.entitlements.changedA tax-filing credit was added or consumedUpdate remaining filings
company.updatedEntity type, state, name suffix, industry, shares, formation date, address or owners changedRefresh the company record
company.dissolvedA dissolution order completed (once)Close the account; renewals stop and open requirements close
tax_filing.createdA federal or state filing was opened (one right consumed)Track the filing
tax_filing.status.changedA filing's status or progress movedShow filing progress
service_order.status.changedAn order was created or moved through fulfilment, including cancellationUpdate the order; branch on status
service_order.completedThe order reached its final step; fires again if it reopens and completes once moreDeliver the result
service_order.updatedOptions or price changed without your call (a reversed upgrade is credited back)Refresh the order
service_order.quotedA quote_pending order was pricedAccept before quote.expires_at; nothing bills until you do
service_order.renewal_canceledYour renewal-cancellation request was approvedShow the renewal_ends_at date
service_order.renewal_cancel_deniedYour renewal-cancellation request was deniedTell the customer it keeps renewing
requirement.createdSomething is needed from you or your customerPrompt the customer
requirement.fulfilledA requirement was resolved; payload carries its responseClear the task
requirement.canceledAn open requirement closed unfulfilled (declined signature, withdrawn ask); cancel_reason says whyClear or escalate the task
requirement.signature.viewedA signer opened a signature document (once per signer)Progress only
requirement.signature.signedA signer signed (once per signer)Progress; requirement.fulfilled follows when the last signs
file.createdA document was published on one of your companiesDownload it from the file's content endpoint
calendar.reminderA compliance deadline is approaching (once per reminder point); payload has due_at and remind_atRelay under your own brand; Clemta sends no mail to your customer
invoice.finalizedA month-end invoice was issuedReconcile 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:

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:

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:

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 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 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 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 adds routing per event family and a full delivery history in front of your Clemta endpoint. Try it with a free account.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.