> 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/documentation/grow-and-monetize/monetization/configure-event-webhooks.md).

# Configure event webhooks

Configure a signed event webhook, test delivery, and monitor retry and suspension behavior.

Podigee Audio Video Ad Server can send selected business and delivery events to an approved webhook endpoint. After the first mention, this article uses Podigee Ad Server for the product name. A webhook sends a signed event after a source event is accepted. It does not replace the event ledger, the analytics pipeline, or the evidence shown in **Monetization > Evidence & Money**.

The webhook is an outbound notification. It must not be used as the only source for billing, delivery qualification, or a listener-level event stream.

## Before you start

* You have permission to configure integrations in the workspace.
* You have an HTTPS endpoint that your receiving system owns.
* You have a stored secret reference and a signing-key owner.
* You know which business events the receiving system needs.
* You know the receiver's retention, replay, and incident contact rules.

Do not paste a secret into the form. Do not subscribe to raw listener events. Podigee sends only approved domain events that the workspace and receiving system are allowed to exchange.

## Create the webhook connection

1. Open **Monetization > Integrations**.
2. Choose **Certify an integration**.
3. Choose **Configure a connector**.
4. Select the workspace where the receiver will run.
5. Choose **Webhook** for the connection purpose.
6. Enter the secure HTTPS endpoint.
7. Select the stored secret reference.
8. Select the signing profile.
9. Select the approved event types.
10. Set the maximum attempt count for the receiver.
11. Confirm the data flow, region, and record-matching rules.
12. Apply the connector configuration.

The event list is controlled. If an event does not appear, the event is not approved for this connection or the workspace does not have the required authority.

![The current One Podigee Orbit partner-operations form shows an operational contact with a name, contact detail, responsibility, and role.](https://2032417310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbqUKO6lljHGzkEAzliPI%2Fuploads%2Fgit-blob-97d3afb9e1583309606b6a021d9f64c594b284e7%2Fdoc-monetization-075-notification-routes.png?alt=media)

*Give every operational route a clear owner and a clear reason for the notification.*

## Understand the signed request

Podigee signs the exact request body with an HMAC SHA-256 signature that includes the request timestamp. The receiver must verify the signature against the stored secret before it accepts the event.

The receiver should:

1. Read the raw request body without changing its bytes.
2. Read the signature and timestamp headers.
3. Reject a missing, malformed, or expired signature.
4. Calculate the HMAC over the timestamp and exact request body.
5. Compare the calculated value with the received value in constant time.
6. Store the event identifier before starting a side effect.
7. Return a successful response only after the event is accepted for processing.

Do not parse and re-serialize JSON before signature verification. A formatting change can produce a different signature.

## Choose event scope

Subscribe only to events that the receiving system can process. Useful examples include:

* integration state changes;
* delivery or platform receipts;
* campaign, Flight, or Creative state changes;
* evidence or measurement corrections; and
* operational cases that require action.

The exact event names and payload fields belong to the API Reference. Use the event schema version shown in the connector and do not infer fields from a previous payload.

An event can describe a state change, a receipt, a correction, or a failed operation. It is not a replacement for reading the current resource. When the event tells the receiver to refresh a resource, use the approved API access and the exact resource version in the event.

## Test the webhook

1. Open the webhook connector version in **Monetization > Integrations**.
2. Send the managed test event.
3. Confirm that the receiver accepts the exact signed body.
4. Confirm that the receiver rejects an invalid signature.
5. Confirm that the receiver rejects an old timestamp.
6. Send the same event again and confirm that it produces one receiver action.
7. Return a temporary failure and confirm that Podigee records a retryable attempt.
8. Return a permanent failure and confirm that Podigee records a terminal attempt.
9. Save the request and response evidence.

The test must prove both delivery and safe failure. A successful HTTP response alone does not prove that the receiver processed the event correctly.

## Monitor delivery and retries

Open **Monetization > Operations** to review webhook delivery attempts. Each attempt has its own request digest, response digest when available, attempt number, state, HTTP status, and next retry time.

The normal states are:

* **Pending:** the event is waiting for its first attempt or next retry.
* **Delivered:** the receiver accepted the event.
* **Retryable failure:** the receiver or network returned a temporary failure.
* **Terminal failure:** Podigee stopped retrying because the failure is permanent or the attempt limit was reached.

The default maximum attempt count is managed by the webhook profile. Do not create a second subscription to compensate for a failed delivery. Repair the endpoint or secret, then retry the original event through its recorded delivery state.

![The current One Podigee Orbit activity record shows the completed partner-operations action with short, copyable references and a completed status.](https://2032417310-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbqUKO6lljHGzkEAzliPI%2Fuploads%2Fgit-blob-19dc99bc7fff181e4ea057a652391b8f4bfd75f5%2Fdoc-monetization-075-notification-receipt.png?alt=media)

*Keep the delivery receipt with the exact connector version that produced it.*

## Activate the webhook

1. Confirm the endpoint, secret reference, signing profile, and event list.
2. Confirm that the managed test passed for valid, invalid, duplicate, temporary-failure, and permanent-failure cases.
3. Confirm that the receiver has an incident owner.
4. Submit the connector for the required review policy.
5. Activate the webhook only when the connector state and evidence are current.
6. Send one live-safe test event after activation.
7. Monitor the first delivery attempts in **Monetization > Operations**.

Activation enables only the selected event types. It does not grant access to other workspace resources or change the delivery decision.

## Suspend or change the webhook

Suspend the webhook when the receiver is unsafe, unavailable, or no longer authorized.

1. Open the webhook in **Monetization > Integrations**.
2. Choose **Suspend**.
3. Confirm the exact connector version and reason.
4. Check for pending, retryable, or terminal delivery attempts.
5. Repair the endpoint or secret in a new connector version.
6. Run the test again before reactivation.

Suspending a webhook does not delete the source event or the delivery evidence. It stops new outbound attempts for that subscription. It does not stop ad delivery, change an active Campaign, or reverse a qualified revenue event.

## If a webhook does not work

* **The test is rejected:** verify the raw-body signature calculation, timestamp tolerance, and stored secret reference.
* **Events arrive twice:** deduplicate by the event identifier before side effects.
* **No events arrive:** confirm the webhook is active and that the event type is selected.
* **Retries continue:** inspect the HTTP status, timeout, response digest, and next retry time.
* **The receiver changed its schema:** create a new connector version and test it. Do not mutate the old event contract.
* **The endpoint is no longer safe:** suspend the webhook and rotate the secret through the approved key process.

Use the API Reference for the exact event schema, signature headers, version fields, and resource links. Use **Monetization > Evidence & Money** for the source event and the commercial or delivery result. Use **Monetization > Operations** for webhook delivery attempts.

## Expected result

The webhook sends only selected, signed domain events to an approved endpoint. The receiver can verify the exact body, reject unsafe or duplicate messages, and recover from temporary failures. Podigee keeps the source event, delivery attempt, and business evidence separate and traceable.


---

# 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/documentation/grow-and-monetize/monetization/configure-event-webhooks.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.