Twelve Salla Order Integration

I built this integration for a client whose Salla orders require fulfillment through Twelve, a digital-goods provider. The middleware receives store events, places eligible orders in a processing queue, buys the requested top-up or voucher, and records the outcome for the store.

The problem

A store order and a provider purchase are separate transactions. Webhooks may be repeated, provider calls may fail temporarily, and a purchase can finish later through a callback. The integration needs to connect those states without treating every retry as a new order.

Key features

• A signed Salla webhook accepts order and store authorization events.
• Order events are deduplicated before fulfillment work is queued.
• A worker checks Twelve balance and resolves product packages from stored mappings.
• Top-up purchases validate the destination before purchase; voucher orders use the provider purchase flow.
• Salla OAuth tokens are refreshed when needed for store API calls.
• Twelve callbacks update purchases that complete asynchronously.
• Product packages are synchronized into a MongoDB cache.
• Definitive failures can add a private note to the Salla order history.

Technical architecture

An Express service receives webhooks and validates their bodies. MongoDB stores store credentials, cached Twelve products, orders, and idempotency records. Redis backs a BullMQ queue. A separate worker reads order jobs, calls Twelve, and updates Salla through its API. Twelve's callback route handles delayed results. The related description_salla_generator integration is a separate Salla service: it responds to product webhooks, asks Gemini for Arabic product descriptions, and writes them back through Salla's API.

Engineering highlights

• Salla signatures are checked against raw request bytes with a timing-safe comparison.
• Store OAuth tokens are encrypted at rest with AES-256-GCM and refreshed after expiry or an unauthorized API response.
• Queue processing distinguishes temporary network failures from final provider rejections.
• MongoDB idempotency records prevent repeated webhook delivery from creating duplicate work.

My role

I built the Salla-to-Twelve middleware, including webhook intake, token handling, fulfillment workers, callbacks, and order updates. I also built the related description generator as a separate integration.