{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks","siteUrl":"https://docs.apiera.io","projectTitle":"Apiera Docs","description":"Real-time event notifications from the Apiera API","lang":"en","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apiera webhooks deliver real-time HTTP notifications when events occur in your organization. Instead of polling for"," ","changes, your application receives a POST request for each event, enabling responsive integrations that react to"," ","changes as they happen."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"design-philosophy","__idx":1},"children":["Design philosophy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apiera uses a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["granular, signal-based"]}," webhook architecture. Every operation across the API surface fires a"," ","corresponding event. Not just top-level resource changes, but sub-resource operations too (e.g."," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.attribute.linked"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.input_value.updated"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Granular events"]}," let integrators know ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["what kind"]}," of change occurred, not just ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["that something changed"]},". A coarse"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.updated"]}," event forces consumers to either fetch-and-diff or maintain complex routing logic. Granular events"," ","allow selective subscriptions and clear intent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Thin payloads"]}," contain only navigational properties: the UUIDs needed to construct the exact REST API call to fetch"," ","current state. Delta payloads (before/after values) are deliberately avoided. While the infrastructure can provide"," ","near-ordered delivery in many cases, delta payloads require ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["guaranteed"]}," ordering to be safe. Out-of-order delivery of"," ","before/after values can corrupt consumer state. Consumers always fetch current state from the API, which is"," ","architecturally sound regardless of delivery order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":2},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Subscribe"]}," - Create a webhook subscription with a target URL and select which event types to receive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Receive"]}," - When an event occurs, Apiera sends an HTTP POST to your endpoint with a signed JSON payload."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify"]}," - Validate the HMAC-SHA256 signature to confirm the request is authentic."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fetch"]}," - Use the UUIDs in the payload to call the corresponding REST endpoint for current state."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setting-up-a-subscription","__idx":3},"children":["Setting up a subscription"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-create-a-subscription","__idx":4},"children":["1. Create a subscription"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.apiera.io/v1/webhook-subscriptions \\\n  -H \"Authorization: Bearer {token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"displayName\": \"My Integration\",\n    \"targetUrl\": \"https://example.com/webhooks\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}," field (format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whsec_<base64>"]},"). ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store this secret securely."]}," It is only returned"," ","on creation and when explicitly rotated. You need it to verify incoming webhook signatures."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"uuid\": \"a1b2c3d4-...\",\n  \"status\": \"active\",\n  \"displayName\": \"My Integration\",\n  \"targetUrl\": \"https://example.com/webhooks\",\n  \"requestTimeoutMs\": 10000,\n  \"secret\": \"whsec_dGhpcyBpcyBhIHNlY3JldA==\",\n  \"createdAt\": \"2026-03-10T12:00:00Z\",\n  \"updatedAt\": \"2026-03-10T12:00:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-subscribe-to-event-types","__idx":5},"children":["2. Subscribe to event types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List available event types, then subscribe to the ones you need:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# List all available event types\ncurl https://api.apiera.io/v1/webhook-event-types \\\n  -H \"Authorization: Bearer {token}\"\n\n# Subscribe to an event type\ncurl -X POST https://api.apiera.io/v1/webhook-subscriptions/{subscriptionUuid}/event-types \\\n  -H \"Authorization: Bearer {token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"webhookEventTypeUuid\": \"event-type-uuid-here\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You only receive events for event types you have explicitly subscribed to."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-manage-your-subscription","__idx":6},"children":["3. Manage your subscription"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint"},"children":["Endpoint"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List subscriptions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get subscription"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update subscription"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PATCH"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete subscription"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DELETE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Activate / Deactivate"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PATCH"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}/actions/lifecycle"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rotate secret"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PATCH"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}/actions/rotate-secret"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List subscribed event types"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["GET"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}/event-types"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Subscribe to event type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["POST"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}/event-types"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unsubscribe from event type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["DELETE"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/webhook-subscriptions/{uuid}/event-types/{eventTypeUuid}"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"subscription-lifecycle","__idx":7},"children":["Subscription lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subscriptions have three states:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["active"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Receives and delivers events normally."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["inactive"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paused. No events are created or delivered."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["suspended"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Temporarily disabled by the system (e.g. persistent delivery failures)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transition between states using the lifecycle endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PATCH https://api.apiera.io/v1/webhook-subscriptions/{uuid}/actions/lifecycle \\\n  -H \"Authorization: Bearer {token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"transition\": \"deactivate\" }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security","__idx":8},"children":["Security"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"signature-verification","__idx":9},"children":["Signature verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every webhook delivery is signed with your subscription's HMAC secret. Always verify the signature before processing"," ","the payload."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each request includes three headers:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique delivery identifier (UUID)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unix timestamp (seconds) when the webhook was sent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HMAC-SHA256 signature in the format ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1,<base64>"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The signature is computed over the string:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{webhook-id}.{webhook-timestamp}.{payload}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{payload}"]}," is the raw JSON request body."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verification steps:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Extract the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]}," headers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Construct the signed content: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{webhook-id}.{webhook-timestamp}.{payload}"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compute HMAC-SHA256 using your secret (Base64-decode the secret after removing the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whsec_"]}," prefix)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare the computed signature with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]}," header value."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally, reject requests where the timestamp is older than 5 minutes to prevent replay attacks."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/webhooks/examples"},"children":["Examples"]}," for complete verification code in multiple languages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rotating-secrets","__idx":10},"children":["Rotating secrets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your secret is compromised, rotate it immediately:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PATCH https://api.apiera.io/v1/webhook-subscriptions/{uuid}/actions/rotate-secret \\\n  -H \"Authorization: Bearer {token}\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains the new ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]},". Update your verification code before the next delivery."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-headers","__idx":11},"children":["Delivery headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every webhook POST request includes these headers:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json; charset=utf-8"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique delivery UUID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unix timestamp (seconds)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook-signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HMAC-SHA256 signature (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1,<base64>"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The event type string (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.created"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Deprecation"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Optional)"]}," RFC 7234 date if the event type is deprecated."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Sunset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Optional)"]}," RFC 7234 date when the event type will be removed."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payload-structure","__idx":12},"children":["Payload structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All payloads are thin. They contain only the UUIDs needed to fetch current state via the REST API."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"productUuid\": \"550e8400-e29b-41d4-a716-446655440000\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payload structure varies by event type but always maps directly to REST API path parameters. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/webhooks/events"},"children":["Events"]}," ","for details on event types and their payloads."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"monitoring-deliveries","__idx":13},"children":["Monitoring deliveries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Track delivery status and debug failures using the delivery endpoints:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# List deliveries for a subscription\ncurl https://api.apiera.io/v1/webhook-subscriptions/{uuid}/deliveries \\\n  -H \"Authorization: Bearer {token}\"\n\n# Get a specific delivery\ncurl https://api.apiera.io/v1/webhook-subscriptions/{uuid}/deliveries/{deliveryUuid} \\\n  -H \"Authorization: Bearer {token}\"\n\n# List delivery attempts\ncurl https://api.apiera.io/v1/webhook-subscriptions/{uuid}/deliveries/{deliveryUuid}/attempts \\\n  -H \"Authorization: Bearer {token}\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each delivery tracks:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivered"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["attempts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of delivery attempts made."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lastStatusCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HTTP status code from the most recent attempt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When the next retry is scheduled (if pending)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each attempt records the HTTP status code, response body (truncated to 2048 characters), and response time in"," ","milliseconds."]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"Design philosophy","id":"design-philosophy","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Setting up a subscription","id":"setting-up-a-subscription","depth":2},{"value":"1. Create a subscription","id":"1-create-a-subscription","depth":3},{"value":"2. Subscribe to event types","id":"2-subscribe-to-event-types","depth":3},{"value":"3. Manage your subscription","id":"3-manage-your-subscription","depth":3},{"value":"Subscription lifecycle","id":"subscription-lifecycle","depth":3},{"value":"Security","id":"security","depth":2},{"value":"Signature verification","id":"signature-verification","depth":3},{"value":"Rotating secrets","id":"rotating-secrets","depth":3},{"value":"Delivery headers","id":"delivery-headers","depth":2},{"value":"Payload structure","id":"payload-structure","depth":2},{"value":"Monitoring deliveries","id":"monitoring-deliveries","depth":2}],"frontmatter":{"seo":{"title":"Webhooks","description":"Real-time event notifications from the Apiera API"}},"lastModified":"2026-03-16T10:52:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}