> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/api-reference/readme/webhooks-and-events.md).

# Webhooks and events

Consume signed events from the Podigee Audio Video Ad Server with at-least-once delivery, safe retry, deduplication, ordering, and evidence boundaries.

The **Podigee Audio Video Ad Server** emits versioned events when a command, operation, Creative, approval, reservation, publication, delivery, platform integration, billing, or finance state changes. Events let a connected system react without polling every resource.

The machine-readable AsyncAPI and JSON Schema files are the authority for exact event type strings, payload fields, and schema URLs. This page explains how to consume them safely.

## Delivery guarantees

| Guarantee            | Meaning                                                                                            |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| At least once        | A valid event can be delivered more than once.                                                     |
| No global order      | Events from different workspaces or subjects can arrive in any order.                              |
| Partitioned order    | Events for the same declared partition key keep the contract order when the transport provides it. |
| Idempotent consumers | Your consumer must accept a duplicate without a second side effect.                                |
| Signed body          | The webhook signature covers the exact request body and timestamp.                                 |
| Named replay         | A replay uses a named event boundary and keeps the original event identity.                        |

Do not use arrival order as business truth. Read the event time, subject version, causation, and current resource state when you need to make a decision.

## Event envelope

Every event uses a versioned envelope with these fields:

| Field                                | Meaning                                                    |
| ------------------------------------ | ---------------------------------------------------------- |
| `specversion`                        | Envelope specification version.                            |
| `id`                                 | Unique event identity.                                     |
| `source`                             | The authority that produced the event.                     |
| `type`                               | Versioned event type from the event catalog.               |
| `subject`                            | The resource or operation that changed.                    |
| `time`                               | Event publication time.                                    |
| `datacontenttype`                    | The payload media type.                                    |
| `dataschema`                         | The exact payload schema reference.                        |
| `workspaceid`                        | The workspace boundary.                                    |
| `authorityepoch`                     | The authority version used for the event.                  |
| `correlationid`                      | The end-to-end business operation correlation.             |
| `causationid`                        | The event or command that caused this event, when present. |
| `traceparent`                        | The distributed trace context, when present.               |
| `releaseid` and `releasedigest`      | The serving version for delivery events, when required.    |
| `decisionid` and `playbacksessionid` | Delivery decision and playback references, when required.  |
| `privacyclass`                       | The allowed handling class for the event.                  |
| `occurredat` and `receivedat`        | Source occurrence and system receipt times.                |
| `deduplicationkey`                   | The stable key used by consumers to ignore duplicates.     |
| `integrity`                          | Digest, algorithm, key ID, and signature information.      |
| `data`                               | The payload defined by the event schema.                   |

The envelope can contain confidential or pseudonymous values. Store only the fields your purpose needs and apply the retention policy for the privacy class.

## Event families

| Family                | What it confirms                                              | Typical consumer                                            |
| --------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
| Command receipt       | A typed management command completed                          | An integration that updates its local state.                |
| Operation completion  | An asynchronous job reached a result                          | A client polling media, forecast, report, or platform work. |
| Creative media        | A Creative preparation changed                                | A campaign or production workflow.                          |
| Approval              | A configured review decision changed                          | An approval or audit system.                                |
| Reservation           | Capacity authorization changed                                | A planning or yield system.                                 |
| Serving publication   | A delivery version changed                                    | A hosting or cache integration.                             |
| Delivery observed     | A trusted delivery boundary observed playback or serving      | Analytics and qualified measurement.                        |
| Presentation binding  | A durable platform presentation resolved                      | Apple or another presentation-bound integration.            |
| Platform integration  | A provider or platform state changed                          | A connector monitor.                                        |
| Billing qualified     | A measurement contract qualified or reversed a billable event | Revenue and reconciliation.                                 |
| Finance posted        | A commercial subledger period changed                         | Finance and accounting.                                     |
| Migration or security | Authority or security state changed                           | Operations and incident response.                           |

An event confirms only its stated boundary. A delivery event does not confirm a finance post. A command receipt does not confirm playback. A platform event does not replace the destination's receipt.

## Configure a webhook consumer

1. Create a service integration with the least-privilege event scope.
2. Register one HTTPS endpoint with a clear owner and purpose.
3. Store the current signing key outside source control and application logs.
4. Subscribe only to the event families required by the purpose.
5. Store the last accepted event ID, deduplication key, and schema version.
6. Return the acknowledgement defined by the webhook contract only after durable receipt.
7. Process business work asynchronously after the receipt is durable.
8. Expose a support view that can show the event ID, subject, result, and retry state.

Do not perform a slow report, finance, or provider call before the webhook acknowledgement. The event sender can retry when your endpoint is slow or unavailable.

## Verify a webhook

The signature covers the exact body and a timestamp. The consumer should:

1. Read the raw request body without reformatting it.
2. Read the signature, key ID, and timestamp headers defined by the contract.
3. Reject a timestamp outside the accepted clock window.
4. Recompute the HMAC with the active key and the exact body.
5. Reject an unknown key, invalid signature, or unsupported algorithm.
6. Validate the envelope and payload against the exact schema version.
7. Check the workspace and purpose boundary.
8. Check the deduplication key before running a side effect.
9. Persist the receipt and acknowledge it.

Never accept an event because the JSON parses. Schema, signature, workspace, authority, and deduplication checks all need to pass.

## Deduplicate and handle order

Use the event's `id` and declared `deduplicationkey`. Store both with the consumer result.

* The same event ID with the same body is a duplicate. Return the original acknowledgement.
* The same deduplication key with a different body is an integrity conflict. Quarantine it.
* A later subject version can arrive before an earlier one. Keep it pending until the required predecessor is available or the contract allows a state read.
* A delivery event with an older release or playback plan must not overwrite a newer projection.
* A reversal is a new event that references the event it reverses. Never delete the original event.

Use subject versions and authority epochs for state order. Do not use a database arrival timestamp as the only ordering rule.

## Retry behavior

The sender retries when it receives a transient failure or cannot reach the endpoint. The receiver should return the contract status for:

| Result                       | Meaning                              | Sender behavior                                          |
| ---------------------------- | ------------------------------------ | -------------------------------------------------------- |
| Success                      | The event is durably accepted        | Do not send it again unless a named replay is requested. |
| Temporary failure            | The receiver cannot accept it now    | Retry with backoff.                                      |
| Authentication failure       | The signature or key is not accepted | Stop and repair the trust configuration.                 |
| Schema failure               | The event cannot be validated        | Quarantine and alert the integration owner.              |
| Permanent business rejection | The event is valid but cannot apply  | Store the reason and follow the recovery link.           |

Use exponential backoff with a bounded retry window. Do not retry a malformed or unauthenticated event forever. Do not acknowledge an event that is only in memory.

## Replay and recovery

Use the named replay boundary when a consumer loses its local state or a corrected schema becomes available. A replay preserves the original event identity and marks the replay operation.

Before a replay:

1. Freeze the consumer projection or create a new projection version.
2. Record the event family, workspace, period, and starting boundary.
3. Confirm that the consumer is idempotent.
4. Replay into a controlled queue.
5. Compare the resulting projection with the authoritative resource or report.
6. Record the replay receipt and close the operation.

Never replay raw listener events by default. The default webhook contract forbids raw listener events. Use qualified delivery, analytics, platform, or finance events with their declared privacy class.

## Delivery, analytics, report, and money evidence

Use these rules when you update another system:

* A delivery event confirms an observation at the trusted serving or playback boundary.
* An analytics event confirms a metric input, not a final report total.
* A report completion event confirms that the report run is ready to read.
* A billing-qualified event confirms a measurement result, including a reversal when present.
* A finance-posted event confirms a subledger post for the declared period and legal entity.
* A payout or invoice is final only when the finance state and receipt say it is closed.

Keep delivery, analytics, report, and money evidence in separate projections. Do not create an invoice from a raw playback event or a report total without the declared qualification state.

## Privacy and retention

Respect the event `privacyclass`, purpose, and retention rule.

* Keep raw identity and credentials out of webhook payloads and logs.
* Redact tokens, provider secrets, and private media URLs in support views.
* Apply retention and erasure to consumer copies as well as the source event.
* Keep commercial-confidential and restricted events in an access-controlled store.
* Do not use a delivery event for a new audience purpose without a policy grant.

## Troubleshoot a missing or repeated event

1. Check the endpoint health and TLS certificate.
2. Check the event delivery log for the event ID and attempt count.
3. Verify the signature key and clock window.
4. Check the schema version and payload validation result.
5. Check the stored deduplication key.
6. Compare the event subject version with the current resource.
7. Inspect the named operation or replay receipt.
8. Reconcile the consumer projection with the authoritative resource or report.

Repeated events are normal under at-least-once delivery. A missing event is an operations problem, not a reason to invent a local state. Use the current resource or a named replay to recover.

## Expected result

The consumer verifies every event, stores it before acknowledgement, handles duplicates and out-of-order delivery, and keeps delivery, analytics, report, and money state separate. A named replay can rebuild a projection without double counting or losing the original evidence.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.podigee.com/api-reference/readme/webhooks-and-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.