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.completedorrequirement.createdevents? - Why is my Clemta webhook verification failing, or why are Hookdeck retries rejected as "timestamp too old"?
Verification (core)
Clemta follows Standard Webhooks:
| Header | Value |
|---|---|
webhook-id | The event id (evt_...); stable across retries, your idempotency key |
webhook-timestamp | Unix seconds of this attempt |
webhook-signature | Space-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):
| Event | Fired when |
|---|---|
company.created | A company you created was accepted |
company.status.changed | A company moved between in_progress, active and cancelled; branch on status |
company.verified | Every owner's identity document is in (once, before incorporation) |
company.incorporated | The state accepted the filing (once) |
company.onboarding.completed | A pre_existing company finished onboarding (once) |
company.name.changed | The legal name changed, usually to clear a state conflict |
company.ein.assigned | The IRS issued the EIN (once); payload carries ein |
company.document.received | An owner uploaded their identity document |
company.entitlements.changed | A tax-filing credit was added or consumed |
company.updated | Entity type, state, name suffix, industry, shares, formation date, address or owners changed |
company.dissolved | A dissolution order completed (once); the company is closed |
tax_filing.created | A federal or state filing was opened |
tax_ | A filing's status or progress moved |
service_ | An order was created or moved through fulfilment, including cancellation |
service_order.completed | The order reached its final step; fires again if it reopens and completes |
service_order.updated | Options or price changed without your call (a reversed upgrade) |
service_order.quoted | A quote_pending order was priced; accept before quote.expires_at |
service_ | Your renewal-cancellation request was approved |
service_ | Your renewal-cancellation request was denied |
requirement.created | Something is needed from you or your customer |
requirement.fulfilled | A requirement was resolved |
requirement.canceled | An open requirement closed unfulfilled; cancel_reason says why |
requirement.signature.viewed | A signer opened a signature document (once per signer) |
requirement.signature.signed | A signer signed (once per signer) |
file.created | A document was published on one of your companies |
calendar.reminder | A compliance deadline is approaching (once per reminder point) |
invoice.finalized | A month-end invoice was issued |
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
- references/overview.md - Event catalog, payload shape, delivery behaviour
- references/setup.md - Create an endpoint, store the secret, rotate it, test
- references/verification.md - Library and manual verification, v1a, gotchas, debugging