Webhooks - Posternity Documentation

Overview

Webhooks provide real-time notifications when events occur in your Posternity account. Instead of polling our API for status updates, we'll send HTTP POST requests to your specified endpoint whenever something happens.

                            Key Benefits
                            Real-time Updates — Instant notifications for all operations
Reduced API Calls — No need to poll for status updates
Reliable Delivery — Automatic retries with exponential backoff
Secure — HMAC signature verification for authenticity
Scalable — Handle high-volume operations efficiently

                        

Studio Webhooks for Agencies

Creative Studio Notifications

Stay updated on your agency workflows with specialized webhooks for creative operations, client approvals, and campaign management.

Studio-Specific Events

STUDIO studio.campaign.completed

Triggered when a multi-asset campaign generation is finished

STUDIO studio.template.approved

Notified when a client approves a template or design

STUDIO studio.batch.progress

Progress updates for batch image generation operations

Agency Workflow Integration

Client Approval Workflows

Automatically notify stakeholders when content is ready for review, with approval status tracking and revision management.

Campaign Management

Track multi-asset campaigns with progress updates, completion notifications, and automatic delivery to client folders.

Brand Compliance

Get notified when content meets or violates brand guidelines, with automatic flagging for manual review.

Asset Organization

Automatically organize generated content into client-specific folders and update your project management systems.

Map Webhooks for Enterprises

Geographic Content Notifications

Monitor location-based content generation and geographic data processing with specialized webhooks for enterprise mapping operations.

Map-Specific Events

MAP map.region.content.ready

Triggered when location-specific content generation is completed

MAP map.gallery.updated

Notified when a geographic gallery is updated with new content

MAP map.cultural.adaptation.completed

Alerted when content has been culturally adapted for specific regions

Enterprise Geographic Features

Multi-Region Processing

Track content generation across multiple geographic regions with region-specific completion notifications and progress tracking.

Location Intelligence

Get notified when location-based content recommendations are ready, with geographic context and cultural adaptations.

Geographic Analytics

Receive updates on content performance across different regions with detailed geographic usage statistics.

Cultural Compliance

Monitor cultural adaptation processes and get alerts for content that requires manual review for cultural sensitivity.

Core Webhook Events

Image Generation Events

IMAGE image.generation.started

Triggered when image generation begins

IMAGE image.generation.completed

Notified when image generation is finished

IMAGE image.generation.failed

Alerted when image generation encounters an error

Video Processing Events

VIDEO video.processing.started

Triggered when video processing begins

VIDEO video.processing.completed

Notified when video processing is finished

Error Events

ERROR operation.failed

Triggered when any operation fails with detailed error information

Webhook Payload Structure

All webhook payloads follow a consistent structure with event metadata and data:

{
  "id": "evt_1234567890",
  "type": "image.generation.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "image_id": "img_abc123",
    "url": "https://cdn.posternity.com/images/abc123.jpg",
    "metadata": {
      "prompt": "A beautiful sunset over mountains",
      "style": "photorealistic",
      "dimensions": "1024x1024"
    }
  },
  "request": {
    "id": "req_xyz789"
  }
}
                        

Security & Verification

All webhooks include HMAC signatures for verification. Verify the signature to ensure the webhook is from Posternity:

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)
                        

                            Security Best Practices
                            Verify Signatures — Always verify HMAC signatures
Use HTTPS — Only accept webhooks over secure connections
Validate Data — Check payload structure and required fields
Idempotency — Handle duplicate webhooks gracefully
Rate Limiting — Implement rate limiting on your endpoints

                        

Retry Logic

If your webhook endpoint returns a non-2xx status code, we'll retry the delivery:

Retry Schedule

Immediate retry
After 1 minute
After 5 minutes
After 15 minutes
After 1 hour

Timeout

Webhooks timeout after 30 seconds. Ensure your endpoint responds quickly.

Dead Letter Queue

Failed webhooks are stored for 7 days for manual retry or debugging.

Setting Up Webhooks

Create Endpoint — Set up a public HTTPS endpoint to receive webhooks
Configure in Dashboard — Add your webhook URL in the Posternity dashboard
Select Events — Choose which events you want to receive
Test Webhook — Use our test endpoint to verify your setup
Monitor Delivery — Check webhook delivery status in your dashboard

Testing Your Webhook

Use our webhook testing tool to send test events to your endpoint and verify your implementation works correctly.