Webhooks

UniPulse handles both incoming webhooks (from external services) and outgoing webhooks (triggered by workflows).

---

Incoming Webhooks

Sources

Source	Events	Verification	Processing Queue
Facebook/Instagram	New comments, messages, account updates	App secret HMAC	webhook-process -> ice-process
TikTok	New comments, account events	Signature header	webhook-process -> ice-process
Stripe	Payment events (invoice.paid, subscription changes)	Stripe signature	payment-webhook
Paymob	Payment result callbacks	HMAC verification	payment-webhook
Shopify	Order created/updated, product changes	Shopify HMAC	webhook-process -> ecommerce-sync / order-sync

Processing Flow

Webhook Endpoint Pattern

// apps/api/src/routes/webhook.routes.ts
router.post('/webhooks/stripe',
  express.raw({ type: 'application/json' }), // Raw body for signature verification
  webhookController.handleStripe
);

router.post('/webhooks/facebook',
  webhookController.handleFacebook
);

router.post('/webhooks/shopify',
  webhookController.handleShopify
);

Security: Signature Verification

Every incoming webhook is verified using provider-specific signature validation before processing:

// Stripe
const event = stripe.webhooks.constructEvent(body, signature, STRIPE_WEBHOOK_SECRET);

// Facebook
const expectedSignature = crypto.createHmac('sha256', APP_SECRET).update(body).digest('hex');
if (signature !== `sha256=${expectedSignature}`) throw new Error('Invalid signature');

// Shopify
const generatedHash = crypto.createHmac('sha256', SHOPIFY_SECRET).update(body).digest('base64');
if (generatedHash !== shopifyHmac) throw new Error('Invalid signature');

---

Outgoing Webhooks

Workflow Webhook Action

Workflows can trigger outgoing HTTP requests to external services as one of the action node types:

Configuration

In the workflow builder, users configure webhook action nodes with:

Setting	Description
URL	Target endpoint URL
Method	HTTP method (POST, PUT, PATCH)
Headers	Custom headers (for authentication)
Payload template	JSON template with variable interpolation
Timeout	Request timeout in seconds
Retry	Number of retries on failure

Payload Template

{
  "event": "{{trigger.event}}",
  "post": {
    "id": "{{post.id}}",
    "caption": "{{post.caption}}",
    "platform": "{{post.platform}}",
    "metrics": {
      "likes": "{{post.metrics.likes}}",
      "reach": "{{post.metrics.reach}}"
    }
  },
  "workspace": "{{workspace.name}}",
  "timestamp": "{{now}}"
}

---

Webhook Management API

Endpoint	Method	Description
/api/v1/webhooks	GET	List configured webhooks
/api/v1/webhooks	POST	Create webhook configuration
/api/v1/webhooks/:id	PATCH	Update webhook
/api/v1/webhooks/:id	DELETE	Delete webhook

---

Webhook Logging

All webhook activity is logged for debugging:

Incoming Webhooks	Outgoing Webhooks
Logged in WebhookConversation model	Logged in WorkflowRun logs
Source, payload, processing status	URL, payload, response code, latency
Available in audit trail	Available in workflow run history

---

Retry Strategy

Type	Strategy	Max Retries
Incoming (processing failure)	Exponential backoff via BullMQ	3
Outgoing (delivery failure)	Exponential backoff	3 (configurable per webhook)

---

Cross-Reference

• Payment Gateways -- payment webhook details
• Social APIs -- social platform webhooks
• E-Commerce APIs -- Shopify webhooks
• Queue System -- webhook-process and payment-webhook queues
• Services -- workflow engine webhook actions