---
title: Error Handling & Best Practices
url: https://docs.kaltura.com/docs/rich-media-cms-apis/integration/webhooks-reference
---

## Error Handling & Best Practices

| Error Code | Meaning | Resolution |
|------------|---------|------------|
| `EVENT_NOTIFICATION_TEMPLATE_NOT_FOUND` | Template ID does not exist | Verify the ID; may have been deleted |
| `EVENT_NOTIFICATION_WRONG_TYPE` | Clone attempted with mismatched type | The `objectType` in clone must match the source template's type |
| `EVENT_NOTIFICATION_TEMPLATE_DUPLICATE_SYSTEM_NAME` | `systemName` already in use | Choose a unique system name |
| `SERVICE_FORBIDDEN` | Plugin not enabled or action restricted | Verify `EVENTNOTIFICATION_PLUGIN_PERMISSION` is enabled on your account |
| `PROPERTY_VALIDATION_NOT_UPDATABLE` | Attempted to update an immutable field | Use `updateStatus` to change status; `eventType` and `eventObjectType` are fixed at clone time |
| `INVALID_KS` | KS expired or lacks privileges | Generate a fresh admin KS with `disableentitlement` |

**Retry strategy:** For HTTP 5xx or timeouts, retry with exponential backoff (1s, 2s, 4s) up to 3 retries. Client errors (`INVALID_KS`, `SERVICE_FORBIDDEN`) require fixing the request.


### Best Practices

- **Clone system templates rather than requesting custom configurations.** System templates provide tested event/condition combinations for common scenarios. Customize URL, payload, and signing after cloning.
- **Verify webhook signatures.** Compute `SHA256(signing_secret + raw_body)` and compare with the `X-KALTURA-SIGNATURE` header to authenticate incoming requests.
- **Return HTTP 200 promptly.** Acknowledge receipt immediately, then process asynchronously. Kaltura retries on 5xx/timeout up to 10 times over ~24 hours.
- **Design for at-least-once delivery.** The same notification may arrive more than once. Implement idempotency using `eventNotificationJobId`.
- **Use `eventDelayedCondition=1` for content workflows.** This ensures webhooks fire only after entries reach READY status, so receivers always get fully-processed content.
- **Use HTTPS endpoints.** Webhook URLs should use TLS for secure transit.
- **Use AppTokens for callback authentication.** Webhook receivers that call back into Kaltura should use AppTokens rather than hardcoded admin secrets.
- **Use Boolean templates as conditions for REACH automation rules.** Boolean notification templates evaluate without dispatching — pair them with `KalturaReachProfile.rules` for conditional auto-processing.


### Related Guides

- **[Session Guide](/docs/getting-started/authentication/ks-overview)** — KS generation and management  
- **[AppTokens API](/docs/getting-started/authentication/app-tokens-overview)** — Secure server-to-server auth for webhook receivers  
- **[Upload & Ingestion](/docs/rich-media-cms-apis/content-management/upload-ingestion-overview)** — Content events that trigger webhooks  
- **[Distribution](/docs/rich-media-cms-apis/integration/distribution)** — Distribution status change events  
- **[Moderation](/docs/rich-media-cms-apis/content-moderation/moderation-overview)** — Content moderation workflows