🔖 Feature description

Currently there's no unified way to receive real-time webhooks from external platforms (Facebook, X, LinkedIn, etc.). Each provider would need bespoke endpoint wiring, duplicating controller logic, verification, and error handling across many files.

This proposes a registry-based inbound webhook system:

• A WebhookProvider interface that any platform can implement
• A provider registry inside IntegrationManager (Map-based, O(1) lookup)
• A single InboundWebhooksController at /inbound-webhooks/:provider that dispatches to the correct handler
• Optional verifyWebhook() for platforms that sign payloads (e.g., Facebook's HMAC-SHA256)

Adding a new provider becomes 3 lines of wiring , no new controllers, no duplicated logic.

🎤 Why is this feature needed ?

Polling external platforms for engagement data (likes, shares, comments) is inefficient and burns through API rate limits. Most social platforms offer webhook subscriptions for real-time event delivery, but Postiz has no unified way to receive them.

A unified webhook system enables:

• Real-time engagement tracking across all supported platforms
• Foundation for auto-reply and notification features
• Cleaner architecture : one controller instead of N per-provider endpoints
• Easy onboarding for contributors adding new platform support

Without this, each new platform integration would need its own controller, its own verification logic, and its own error handling , leading to code duplication and maintenance burden.

✌️ How do you aim to achieve this?

Implementation uses a registry pattern with 4 components:

1. WebhookProvider interface (libraries/nestjs-libraries/src/integrations/webhook.provider.ts)

   • providerName: string
   • handleWebhook(payload, headers): Promise<WebhookResponse>
   • verifyWebhook?(payload, headers): Promise<boolean> (optional)

2. Registry in IntegrationManager (integration.manager.ts)

   • registerWebhookProvider() / getWebhookProvider() / getRegisteredWebhookProviders()
   • Providers registered at startup via onModuleInit()

3. InboundWebhooksController (apps/backend/src/api/routes/inbound-webhooks.controller.ts)

   • POST /inbound-webhooks/:provider → resolve → verify → dispatch
   • GET /inbound-webhooks → list registered providers (health check)
   • Unauthenticated (external platforms call it directly)

4. FacebookWebhookProvider (reference implementation)

   • Handles hub.challenge verification flow
   • Logs page/post change events
   • Placeholder for HMAC-SHA256 signature verification

Implementation is on branch feature/unified-webhook-registry , PR ready.

🔄️ Additional Information

Design alternatives considered:

• Decorator-based auto-discovery: Using custom decorators + reflection to auto-register providers. Rejected because explicit registration in onModuleInit() is easier to reason about, test, and debug.
• Extending existing /webhooks controller: The existing WebhookController handles outbound webhook CRUD for organizations. Inbound platform hooks are a fundamentally different concern (no auth, external callers, signature verification), so a separate /inbound-webhooks path avoids collision and confusion.
• Per-provider controllers: Would work but leads to duplicated verification/error-handling logic and controller sprawl as more platforms are added.

👀 Have you spent some time to check if this feature request has been raised before?

• I checked and didn't find similar issue

Are you willing to submit PR?

Yes I am willing to submit a PR!