Agent skill

Clemta Webhooks Skill

Receive and verify Clemta webhooks, which use Standard Webhooks signatures. Use when setting up a Clemta partner webhook endpoint, getting the whsec_ signing secret, debugging webhook-id / webhook-timestamp / webhook-signature verification, or handling company, tax filing, service order and requirement events like company.created, company.incorporated, company.ein.assigned, service_order.completed and requirement.fulfilled.

Install this skill

npx skills add hookdeck/webhook-skills --skill clemta-webhooks


Clemta is a US company-formation and compliance API for partners: companies, tax filings, service orders, requirements, files, calendar reminders and invoices. When something happens to a company you created, Clemta POSTs a JSON event to the endpoint you registered on the Webhooks page of the partner dashboard. The same events can be polled from GET /events.

When to Use This Skill

  • How do I receive Clemta webhooks?
  • How do I verify a Clemta webhook signature (webhook-signature)?
  • Where do I find my Clemta signing secret (whsec_...)?
  • How do I handle company.incorporated, company.ein.assigned, service_order.completed or requirement.created events?
  • Why is my Clemta webhook verification failing, or why are Hookdeck retries rejected as "timestamp too old"?

Verification (core)

Clemta follows Standard Webhooks:

HeaderValue
webhook-idThe event id (evt_...); stable across retries, your idempotency key
webhook-timestampUnix seconds of this attempt
webhook-signatureSpace-separated entries: v1,<base64> (HMAC) and v1a,<base64> (Ed25519)

Clemta also sends Clemta-Webhook-Id, -Timestamp and -Signature copies of the same values. Signed content is {webhook-id}.{webhook-timestamp}.{raw body}, HMAC-SHA256, base64 output. The key is the base64-decoded part of the whsec_... secret after the prefix. Compare against every v1, entry (two during a secret rotation) and skip other versions such as v1a. If webhook-id is absent, read svix-id, svix-timestamp and svix-signature instead. The examples use the standardwebhooks library (npm and PyPI):

const { Webhook } = require('standardwebhooks');

// rawBody: exact request body as a string, NOT re-serialised JSON
function verifyClemta(rawBody, headers, secret = process.env.CLEMTA_WEBHOOK_SECRET) {
  const p = headers['webhook-id'] ? 'webhook' : 'svix'; // fall back to the svix-* names
  const [id, timestamp, signature] = ['id', 'timestamp', 'signature'].map((k) => headers[`${p}-${k}`]);
  new Webhook(secret).verify(rawBody, {
    'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
  }); // throws on a bad signature or stale timestamp → respond 400
}

The library always enforces a fixed 5-minute timestamp window. Hookdeck retries and replays resend the original webhook-timestamp, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in references/verification.md, which can drop or widen the window. In Express, read the body with express.raw({ type: '*/*' }) so any content type verifies, and parse JSON only after the check.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Payload

The body is { type, data }. data.object is the resource in its API shape, and its own object field names the resource kind. The payload is rendered at the API version pinned on the endpoint.

{ "type": "company.ein.assigned",
  "data": { "object": { "object": "company", "id": "cmp_...", "ein": "12-3456789" } } }

Common Event Types

27 types are documented (the list may not be exhaustive, so ignore types you don't recognise):

EventFired when
company.createdA company you created was accepted
company.status.changedA company moved between in_progress, active and cancelled; branch on status
company.verifiedEvery owner's identity document is in (once, before incorporation)
company.incorporatedThe state accepted the filing (once)
company.onboarding.completedA pre_existing company finished onboarding (once)
company.name.changedThe legal name changed, usually to clear a state conflict
company.ein.assignedThe IRS issued the EIN (once); payload carries ein
company.document.receivedAn owner uploaded their identity document
company.entitlements.changedA tax-filing credit was added or consumed
company.updatedEntity type, state, name suffix, industry, shares, formation date, address or owners changed
company.dissolvedA dissolution order completed (once); the company is closed
tax_filing.createdA federal or state filing was opened
tax_filing.status.changedA filing's status or progress moved
service_order.status.changedAn order was created or moved through fulfilment, including cancellation
service_order.completedThe order reached its final step; fires again if it reopens and completes
service_order.updatedOptions or price changed without your call (a reversed upgrade)
service_order.quotedA quote_pending order was priced; accept before quote.expires_at
service_order.renewal_canceledYour renewal-cancellation request was approved
service_order.renewal_cancel_deniedYour renewal-cancellation request was denied
requirement.createdSomething is needed from you or your customer
requirement.fulfilledA requirement was resolved
requirement.canceledAn open requirement closed unfulfilled; cancel_reason says why
requirement.signature.viewedA signer opened a signature document (once per signer)
requirement.signature.signedA signer signed (once per signer)
file.createdA document was published on one of your companies
calendar.reminderA compliance deadline is approaching (once per reminder point)
invoice.finalizedA month-end invoice was issued

See references/overview.md.

Delivery Semantics

Return 2xx to acknowledge. Anything else, a timeout or a 3xx (redirects are not followed) is retried up to 20 times with jittered exponential backoff, 15 seconds to 6 hours apart. Delivery is ordered best effort per endpoint and paced one at a time; an event that keeps failing is set aside, so tolerate reordering and deduplicate on webhook-id. Retry-After on 429 or 503 is honoured. Answer 410 Gone to disable the endpoint; an endpoint failing for three days is disabled automatically. Replay missed events from GET /events. Return 400 for missing headers or a bad signature, and fail closed (500) when the secret is not set.

Environment Variables

CLEMTA_WEBHOOK_SECRET=whsec_xxxxx   # full value, shown once at endpoint creation; handlers fail closed (500) without it

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 clemta --path /webhooks/clemta

Use the printed URL as the endpoint URL on the Webhooks page of the Clemta partner dashboard.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →