webhooks.create
Register a new webhook endpoint to receive real-time events.
Prerequisites
- A Curviate API key, passed as
apiKeywhen you construct the client. Authentication and accounts shows how to create one. - A connected LinkedIn account. This call takes a real account id owned by your tenant; a placeholder is rejected. Authentication and accounts covers connecting one, and accounts.list returns the
account_idof each account already connected.
Signature
create(body: WebhookCreateBody): Promise<WebhookCreateResult>Example
import { Curviate } from "@curviate/sdk";
const curviate = new Curviate({
apiKey: "cvt_live_...",
baseUrl: "https://api.curviate.com",
});
const result = await curviate.webhooks.create({ source: "messaging", request_url: "https://example.com/webhooks/curviate", account_ids: ["acc_YOUR_ACCOUNT_ID"] });
console.log(result.id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
source | string | Yes | Body parameter. |
request_url | string | Yes | HTTPS URL that receives webhook deliveries. Must be a publicly reachable host on the default https port; private, loopback and link-local addresses are rejected. |
name | string | No | Human-readable name for this webhook (1-100 chars) |
account_ids | array | Yes | Per-account targeting. Required and non-empty; each id must be an acc_-prefixed id owned by the tenant. |
enabled | boolean | No | A disabled webhook is created but delivers nothing |
headers | array | No | Custom headers added to each delivery POST. Names must be valid HTTP header names and values must be printable ASCII (no line breaks or control characters). Reserved names are rejected at registration; they include Content-Type, User-Agent, Host, any Curviate-* or Sec-* name, and the hop-by-hop headers. At most 10 headers, 1024 characters per value, 4096 bytes in total. Custom headers are not covered by the delivery signature, so treat them as a hint, not as proof of origin. Values are encrypted at rest and are never returned by a read. A read shows the header name plus a masked value: the first 8 characters followed by "..." when the value is at least 24 characters long, and a fixed "********" for anything shorter, so a short value is never disclosed by its own preview. The header name is what identifies which credential is configured. |
events | array | No | Messaging events to subscribe to (default: [message.received]) |
data | array | No | Field-remapping keys for the messaging delivery payload |
Returns
Resolves to WebhookCreateResult. Top-level fields: object, id, source, request_url, name, account_ids, enabled, headers, events, data, secret, secret_prefix, created_at.
Error codes
| Code | What it means, and what to do |
|---|---|
UNAUTHORIZED | The API key is missing, malformed, or revoked. Check the key you passed to the client. |
INVALID_REQUEST | A parameter failed validation. The message names the offending field; fix the request rather than retrying it. |
RATE_LIMIT_ACCOUNT | This account's own quota is exhausted. Wait for the window in the Retry-After header, then retry. |
RATE_LIMIT_TENANT | The tenant-wide quota is exhausted across all accounts. Slow the whole workload, not just this call. |
PLATFORM_RATE_LIMIT | LinkedIn is throttling this account. Back off well beyond the hinted delay; sustained pressure risks the account. |
PLATFORM_ERROR | A transient upstream failure. Retry once with backoff before treating it as a real error. |
ACCOUNT_NOT_FOUND | No connected account with that id belongs to this tenant. List your accounts to get a current id. |
PAYMENT_REQUIRED | The tenant has no active subscription. Subscribe, then retry. |
RESOURCE_NOT_FOUND | The id in the path does not exist, or is not visible to this account. Re-read it from the list endpoint that produced it. |
Every code above is a stable CurviateError.code you can branch on. The full list, the response envelope, and retry semantics are in the Error codes reference.
Next steps
webhooks.list: List the tenant's registered webhooks, cursor-paginated.webhooks.listEvents: Return the complete canonical webhook event catalogue, grouped by source.webhooks.get: Return a single webhook owned by the calling tenant.- SDK Quick Start: installation, the client, account scoping, and pagination.