Webhook Integration

Receive real-time notifications when events occur in your KonPro account. Webhooks allow you to build event-driven integrations and automate workflows.

About Webhooks

Webhooks are HTTP callbacks that notify your application when specific events occur. Instead of polling the API repeatedly, KonPro sends POST requests to your configured endpoint whenever an event happens, enabling real-time, event-driven integrations.

Benefits:

Real-time notifications without polling
Reduced API calls and server load
Event-driven architecture for better scalability
Automated workflows and integrations

How Webhooks Work

Register a webhook endpoint: Use the Add Webhook Endpoint API to register your HTTPS URL.
Subscribe to events: Specify which events you want to receive (e.g., avatar_video.success, avatar_video.fail).
Receive notifications: KonPro sends POST requests to your endpoint when subscribed events occur.
Process events: Your server processes the webhook payload and performs actions based on the event type.
Acknowledge receipt: Return a 200 status code to confirm you received the webhook.

Security Best Practices

⚠️ Important Security Considerations

Use HTTPS: Webhook endpoints must use HTTPS with SSL security level 2 or higher. HTTP endpoints are not supported.
Verify webhook signatures: Always verify webhook signatures to ensure requests are from KonPro (implementation details coming soon).
Validate payloads: Validate all incoming data before processing to prevent injection attacks.
Idempotency: Design your webhook handlers to be idempotent - processing the same event multiple times should be safe.
Rate limiting: Implement rate limiting on your webhook endpoint to prevent abuse.
Error handling: Return appropriate HTTP status codes and handle errors gracefully.

Available Webhook Events

KonPro supports the following webhook event types. Use the List Available Webhook Events endpoint to get the latest list.

Event Type	Description
avatar_video.success	Triggered when an avatar video is successfully generated
avatar_video.fail	Triggered when avatar video generation fails
video_translate.success	Triggered when video translation completes successfully
video_translate.fail	Triggered when video translation fails
personalized_video	Triggered for personalized video events

Webhook Payload Structure

All webhook payloads follow a consistent structure with event_type and event_data fields.

General Payload Format

json

{
  "event_type": "avatar_video.success",
  "event_data": {
    "video_id": "video-123",
    "url": "https://example.com/video.mp4",
    "gif_download_url": "https://example.com/video.gif",
    "video_share_page_url": "https://example.com/share/video-123",
    "folder_id": "folder-456",
    "callback_id": "callback-789"
  }
}

Field	Type	Description
event_type	string	The type of event that occurred (e.g., `avatar_video.success`)
event_data	object	Event-specific data containing details about the event
event_data.video_id	string	Unique identifier for the video
event_data.url	string	URL to access the generated video
event_data.error	string	Error message (present in failure events)

Webhook Receiver Examples

Here are example implementations for receiving and processing webhooks in different programming languages:

Select Language:

javascript

Webhook API Endpoints

Use these API endpoints to manage your webhook subscriptions:

POSTAdd Webhook Endpoint

GETList Webhook Endpoints

Retrieve all registered webhook endpoints for your account.

PUTUpdate Webhook Endpoint

Update an existing webhook endpoint configuration.

GETList Available Webhook Events

Get a list of all available webhook event types you can subscribe to.

Best Practices

Respond quickly: Return a 200 status code as soon as you receive the webhook. Process the event asynchronously if needed.
Handle duplicates: Webhooks may be retried if your endpoint doesn't respond. Use idempotency keys to handle duplicate events.
Queue processing: For time-consuming operations, queue webhook events for background processing.
Log everything: Log all incoming webhooks for debugging and auditing purposes.
Monitor failures: Set up alerts for webhook delivery failures and retry mechanisms.
Test thoroughly: Use webhook testing tools or the KonPro dashboard to test your endpoint before going live.
Version your endpoints: Include version information in your webhook URL to support future changes.

Notes

Webhook endpoints must be publicly accessible via HTTPS.
Your endpoint should respond with a 200 status code within 5 seconds to acknowledge receipt.
KonPro will retry failed webhook deliveries with exponential backoff.
You can subscribe to all events by providing an empty array or omitting the events parameter.
Use the entity_id parameter to filter events for specific resources.
For more details on webhook events, see Webhook Events Documentation.
For implementation examples, see Write Endpoint to Process Webhook Events.

Widget Integration Add Webhook Endpoint