Skip to main content
View as Markdown

Error Handling & Best Practices - Integration

Error Handling & Best Practices​

Error CodeMeaningResolution
EVENT_NOTIFICATION_TEMPLATE_NOT_FOUNDTemplate ID does not existVerify the ID; may have been deleted
EVENT_NOTIFICATION_WRONG_TYPEClone attempted with mismatched typeThe objectType in clone must match the source template's type
EVENT_NOTIFICATION_TEMPLATE_DUPLICATE_SYSTEM_NAMEsystemName already in useChoose a unique system name
SERVICE_FORBIDDENPlugin not enabled or action restrictedVerify EVENTNOTIFICATION_PLUGIN_PERMISSION is enabled on your account
PROPERTY_VALIDATION_NOT_UPDATABLEAttempted to update an immutable fieldUse updateStatus to change status; eventType and eventObjectType are fixed at clone time
INVALID_KSKS expired or lacks privilegesGenerate 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.