{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Subscription model","meta":[{"name":"robots","content":"noindex"}],"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":"subscription-model","__idx":0},"children":["Subscription model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page explains how webhook subscriptions are structured, how you can control which events to receive, and how delivery to your endpoints works."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each subscription is created with the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription"},"children":["Create Webhook Subscription"]}," API."," ","A subscription is owned by a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriberId"]}," (the company that manages it), delivers to a single HTTPS ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]},", lists the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventTypes"]}," you want to receive, and optionally narrows the source companies whose events you receive through an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventSource"]}," object. When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventSource"]}," is omitted, it defaults to the subscriber's own company (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPANY = subscriberId"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A sample create subscription request looks like this:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/webhooks/subscriptions","header":{"title":"POST /v3/webhooks/subscriptions","controls":{"copy":{}}},"source":"{\n \"subscriberId\": \"company1-id\",\n \"name\": \"spotnana_us\",\n \"url\": \"https://partner.com/api/webhooks/pnr\",\n \"eventTypes\": [\"PNR_V3\"],\n \"eventSource\": {\n \"scopes\": [\n { \"predicates\": [ { \"type\": \"COMPANY\", \"comparator\": \"IN\", \"values\": [\"company1-id\"] } ] }\n ]\n },\n \"customHeaders\": { \"X-Custom-Header\": \"my-value\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response returns the subscription ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacSigningSecret"]}," that is shown only once."," ","Store this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmacSigningSecret"]}," securely (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/webhooks/webhook-auth#hmac-signature-verification"},"children":["Authentication"]}," for more information)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"supported-subscription-models","__idx":1},"children":["Supported subscription models"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Spotnana supports two ways to configure webhook subscriptions depending on how your system is set up."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-a-single-tmc-level-webhook-recommended","__idx":2},"children":["Option A: Single TMC-level webhook (recommended)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One webhook subscription that covers all of your customers."," ","Spotnana delivers all events across all organizations to a single endpoint,"," ","and you route them internally based on the organization identifier (i.e., an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organizationId"]},") included in every payload."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"flowchart LR\n S[Spotnana] --> E[Single TMC partner's\n endpoint]\n E --> R{Route by organization ID}\n R --> O1[Org A]\n R --> O2[Org B]\n R --> O3[Org C]\n","diagramHtml":"

Spotnana

Single TMC partner's
endpoint

Route by organization ID

Org A

Org B

Org C

"},"children":["flowchart LR\n S[Spotnana] --> E[Single TMC partner's\n endpoint]\n E --> R{Route by organization ID}\n R --> O1[Org A]\n R --> O2[Org B]\n R --> O3[Org C]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"This is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["recommended"]}," model for partners integrating across multiple customers as it"," ","reduces the overhead of managing multiple subscriptions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this model, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriberId"]}," to your TMC and scope the subscription to every company that TMC manages with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONTRACTING_TMC"]}," predicate. Companies you onboard later are covered automatically, with no subscription changes:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/webhooks/subscriptions","header":{"title":"POST /v3/webhooks/subscriptions","controls":{"copy":{}}},"source":"\"eventSource\": {\n \"scopes\": [\n {\n \"predicates\": [\n {\n \"type\": \"CONTRACTING_TMC\",\n \"comparator\": \"IN\",\n \"values\": [\n \"your-tmc-id\"\n ]\n }\n ]\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To scope a single TMC-level subscription to a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["specific subset"]}," of the companies you manage (rather than all of them), use a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPANY"]}," predicate that lists those company IDs."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]}," are matched with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IN"]}," logic, so the subscription receives events from any company in the list:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/webhooks/subscriptions","header":{"title":"POST /v3/webhooks/subscriptions","controls":{"copy":{}}},"source":"\"eventSource\": {\n \"scopes\": [\n {\n \"predicates\": [\n {\n \"type\": \"COMPANY\",\n \"comparator\": \"IN\",\n \"values\": [\n \"company1-id\",\n \"company2-id\",\n \"company3-id\"\n ]\n }\n ]\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-b-organization-specific-webhooks","__idx":3},"children":["Option B: Organization specific webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each customer organization has its own dedicated webhook subscription with a separate endpoint URL and authentication credentials."," ","Spotnana delivers events for that organization exclusively to the configured endpoint."]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"flowchart LR\n S([Spotnana]) --> E1[[Endpoint A]]\n S --> E2[[Endpoint B]]\n S --> E3[[Endpoint C]]\n E1 --> O1[(Org A)]\n E2 --> O2[(Org B)]\n E3 --> O3[(Org C)]\n","diagramHtml":"

Spotnana

Endpoint A

Endpoint B

Endpoint C

Org A

Org B

Org C

"},"children":["flowchart LR\n S([Spotnana]) --> E1[[Endpoint A]]\n S --> E2[[Endpoint B]]\n S --> E3[[Endpoint C]]\n E1 --> O1[(Org A)]\n E2 --> O2[(Org B)]\n E3 --> O3[(Org C)]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"This model is a good fit for partners who manage distinct integrations per customer."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For each subscription, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriberId"]}," to the organization it serves."," ","You can either omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventSource"]}," (it defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPANY = subscriberId"]},") or set it explicitly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"POST /v3/webhooks/subscriptions","header":{"title":"POST /v3/webhooks/subscriptions","controls":{"copy":{}}},"source":"\"eventSource\": {\n \"scopes\": [\n { \"predicates\": [ { \"type\": \"COMPANY\", \"comparator\": \"IN\", \"values\": [\"company1-id\"] } ] }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," While our platform supports this subscription model we do not prefer this approach as it requires separate"," ","setup for each organization. We recommend using option A instead."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-and-operation-filtering","__idx":4},"children":["Event and operation filtering"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Partners can choose which event and operations that they wish to receive. You can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subscribe to only specific webhook events through the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventTypes"]}," field (e.g., ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/openapi/webhookeventapi/webhooks/paths/pnr_v3/post"},"children":["PNR_V3"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Control which company's events a subscription receives through the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventSource"]}," object. If the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventSource"]}," is omitted, the subscription defaults to the subscriber's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["companyId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Route a delivered event to the right customer within a single TMC-level subscription using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," > ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organizationId"]}," field included in every payload."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," Currently the operation filtering is implemented as a blacklist (i.e., to exclude specific operations that you don't want to receive)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-delivery","__idx":5},"children":["Event delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here are some important points to note regarding webhook delivery:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhooks support payload delivery to one endpoint per subscription."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can create multiple subscriptions (each delivering to its own endpoint) using the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/docs/openapi/webhooksubscriptionapi/webhook-subscription/createwebhooksubscription"},"children":["Create Webhook Subscription API"]},"."]}]}]},"headings":[{"value":"Subscription model","id":"subscription-model","depth":1},{"value":"Supported subscription models","id":"supported-subscription-models","depth":2},{"value":"Option A: Single TMC-level webhook (recommended)","id":"option-a-single-tmc-level-webhook-recommended","depth":3},{"value":"Option B: Organization specific webhooks","id":"option-b-organization-specific-webhooks","depth":3},{"value":"Event and operation filtering","id":"event-and-operation-filtering","depth":2},{"value":"Event delivery","id":"event-delivery","depth":2}],"frontmatter":{"seo":{"title":"Subscription model"}},"lastModified":"2026-06-18T12:59:39.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks/webhook-config-model","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}