Wire Shopify order-shipped events to Podium review requests and operate the delivery layer in production. This is not a campaign-builder walkthrough — it is the integration code your system runs when a merchant ships 300 orders on Black Friday, when a customer initiates a refund 30 minutes after the request fires, when a carrier silently drops the SMS, when a 1-star review-response webhook never arrives, and when an opt-out from a different marketing flow needs to suppress the review-request path.
The six production failures this skill prevents:
Review requests sent during cooldown — A customer received a review request 5 days ago; a new Shopify shipment triggers another within the cooldown window. The customer is annoyed, replies STOP, and Podium suspends the account for spam-pattern volume. A naive integration has no cooldown gate and rediscovers this rule with every new merchant.
Shopify-ship-event race with refund — An order ships, the orders/fulfilled webhook fires, the review request is sent, and 30 minutes later the customer initiates a refund. The review request is now embarrassing and brand-damaging. Without a delay window between fulfillment and send, every refund-prone product line generates this incident.
Failed-send silent rejection — Podium accepts the POST /v4/review-invitations call and returns 200 with an invitation_id. Hours later the actual SMS send is rejected at the carrier (T-Mobile filter, invalid number, opt-out on the destination). The integration thinks it succeeded. The merchant's review velocity quietly drops.
Review-response webhook drops — A customer leaves a 1-star review. Podium fires the review.received webhook. The receiver returns 500 due to a deployment, Podium retries 3 times, then gives up. The team finds out a week later from Google directly. Without webhook persistence + replay + idempotency, low-volume signal evaporates.
Multi-platform routing misconfig — A campaign is configured to route review requests to Facebook, but the customer doesn't have Facebook. The request quietly fails to land — Podium's response shows "delivered" because the SMS went out, but the destination link 404s on the customer's device. Without per-customer platform validation, the merchant's review pipeline silently caters to the wrong network.
Opt-out compliance gaps — A customer opted out of marketing SMS 6 months ago, but the opt-out flag sits on the email-marketing flow only. The Podium review-request flow has its own consent path and fires anyway. The merchant catches a TCPA complaint. Opt-out must be a single check across every flow that touches the contact, not per-channel.
Prerequisites
Python 3.10+ with httpx and redis (or sqlite3 for the SQLite cooldown backend)
A Podium OAuth app authenticated via the podium-auth sibling skill — this skill assumes auth.get_token() is available
A Shopify store with orders/fulfilled webhook configured pointing at this integration
Redis (production) or SQLite (single-node) for cooldown state — keyed by phone number, value is last_contact_at epoch seconds
A persistent inbox for Podium review.received webhooks — see the podium-webhook-reliability sibling skill for the durable-queue pattern this skill consumes
An opt-out source-of-truth table that aggregates marketing-SMS, transactional-SMS, and review-flow opt-outs into a single contact-level boolean — see the podium-contact-dedup sibling skill for the merge semantics this skill relies on
Instructions
Build in this order. Each section neutralizes one production failure mode.
Cooldown is a contact-level rate limit, not a campaign-level one. A customer who places two orders in three days must not get two review requests. Key the cooldown by normalized E.164 phone (the canonical contact identifier across Podium and Shopify) and store last_contact_at as epoch seconds.
import time
import redis
from typing importOptionalclassCooldownGate:
DEFAULT_COOLDOWN_DAYS = 30def__init__(self, redis_url: str, cooldown_days: int = DEFAULT_COOLDOWN_DAYS):
self.r = redis.from_url(redis_url, decode_responses=True)
self.cooldown_seconds = cooldown_days * 86400def_key(self, phone_e164: str) -> str:
returnf"podium:cooldown:{phone_e164}"defcan_send(self, phone_e164: str) -> tuple[bool, Optional[float]]:
"""Returns (allowed, seconds_remaining_if_blocked)."""
last = self.r.get(self._key(phone_e164))
if last isNone:
returnTrue, None
elapsed = time.time() - float(last)
if elapsed >= self.cooldown_seconds:
returnTrue, NonereturnFalse, self.cooldown_seconds - elapsed
defmark_sent(self, phone_e164: str) -> None:
# SETEX with the cooldown window — Redis auto-expires the key, so old contacts roll off.self.r.setex(self._key(phone_e164), self.cooldown_seconds, time.time())
The cooldown window default is 30 days — adjust per-merchant in config/settings.yaml. Critically, mark_sent runs after Podium accepts the API call, but the cooldown is the gate for the decision — never let two concurrent webhook handlers both pass the check and both send.
Shopify's orders/fulfilled fires the moment the merchant marks a shipment as packed and labeled. Customer receipt of the package — and the window for refund decisions before review-worthiness exists — happens hours to days later. Buffer the send by a configurable delay (default 5 days from fulfilled_at), and re-check the order's refund status at send time:
asyncdefschedule_review_request(order: dict, send_after: float) -> None:
"""Schedule, do not send-now. The actual send is gated at fire time on refund status."""await delayed_queue.enqueue(
topic="podium.review.send",
payload={"order_id": order["id"], "phone": order["customer"]["phone"]},
not_before=send_after,
)
asyncdeffire_scheduled_send(payload: dict) -> None:
order = await shopify.get_order(payload["order_id"])
# Refund check at send time — order may have been refunded in the buffer windowif order.get("financial_status") in {"refunded", "partially_refunded", "voided"}:
log_event("review_send_skipped_refund", order_id=order["id"])
returnif order.get("cancelled_at") isnotNone:
log_event("review_send_skipped_cancelled", order_id=order["id"])
returnawait send_review_request(order)
The delayed queue must survive process restart — Redis streams, SQS with DLQ, or Postgres-backed pgmq all work. An in-memory asyncio.sleep does not.
The Podium API's POST /v4/review-invitations response only confirms the invitation record was created — it does not confirm the SMS was delivered to the carrier. Subscribe to review_invitation.failed and review_invitation.delivered webhooks separately, persist them keyed by invitation_id, and reconcile delivery state against the original request after a 24-hour SLA window:
classInvitationOutbox:
"""Tracks every send → carrier-confirmed-delivered transition. Anything unresolved after 24h is escalated."""defrecord_sent(self, invitation_id: str, phone: str, order_id: str) -> None:
self.r.hset(f"podium:inv:{invitation_id}", mapping={
"status": "sent",
"phone": phone,
"order_id": order_id,
"sent_at": time.time(),
})
self.r.expire(f"podium:inv:{invitation_id}", 86400 * 7)
defrecord_delivered(self, invitation_id: str) -> None:
self.r.hset(f"podium:inv:{invitation_id}", "status", "delivered")
self.r.hset(f"podium:inv:{invitation_id}", "delivered_at", time.time())
defrecord_failed(self, invitation_id: str, reason: str) -> None:
self.r.hset(f"podium:inv:{invitation_id}", "status", "failed")
self.r.hset(f"podium:inv:{invitation_id}", "failure_reason", reason)
# Critical: roll back the cooldown — the customer never received the message,# so blocking them from a future request is wrong.
phone = self.r.hget(f"podium:inv:{invitation_id}", "phone")
if phone:
self.r.delete(f"podium:cooldown:{phone}")
The cooldown-rollback step on failed is non-obvious and important. Treating a failed send as a "did contact" decision punishes a customer for a carrier filter they did not ask for.
Podium fires review.received when a customer leaves a review on any routed platform. The webhook must be idempotent (Podium retries on any non-2xx for up to 3 attempts) and must classify sentiment so negative reviews escalate while positive reviews land in a thank-you flow:
Persistence under load is covered by the podium-webhook-reliability sibling skill. The classification step is the application-level contract — wire escalate_negative_review to a Slack/email channel with response SLA, and thank_positive_reviewer to a follow-up campaign.
A merchant configures a Podium campaign to route requests to Facebook. The SMS goes out, but the link inside it lands on facebook.com/{merchant-page}/reviews — which only works if the customer is logged into Facebook on the receiving device. Many customers don't have Facebook at all. Without per-customer platform inference, the merchant's review pipeline silently fails.
Validate platform routing at request-time against a customer profile if one exists, and fall back to a known-good default (Podium's own webchat review) when the configured target is uncertain:
defselect_review_platform(customer: dict, campaign: dict) -> str:
"""Choose the highest-confidence platform for this customer.
Priority: explicit customer preference > campaign default > podium-webchat fallback.
"""if customer.get("preferred_review_platform"):
return customer["preferred_review_platform"]
target = campaign.get("default_platform", "google")
# Light heuristic: prefer google over facebook for unknown-platform customers.# Facebook reviews require a logged-in account; google reviews work for anyone.if target == "facebook"andnot customer.get("facebook_uid"):
return"google"return target
Track the chosen platform on the invitation record so post-hoc analysis can identify route-misconfig patterns. The fallback to Google is conservative on purpose — Google reviews always render publicly and don't require a customer account.
A customer opting out of any flow — marketing SMS, transactional SMS, review requests, account emails — should suppress every flow that touches them. Implementing per-flow opt-out separately is how merchants accumulate TCPA exposure.
The unified check sits in front of mark_sent:
asyncdefis_opted_out(phone_e164: str) -> bool:
"""Returns True if the contact has opted out of ANY flow that suppresses this one."""# Source of truth: the merged contact record from podium-contact-dedup.
contact = await contacts.get_by_phone(phone_e164)
if contact isNone:
returnFalsereturnany([
contact.get("marketing_sms_opt_out", False),
contact.get("review_request_opt_out", False),
contact.get("global_unsubscribe", False),
# STOP reply on any prior message — Podium tracks this at the contact level.
contact.get("podium_keyword_optout", False),
])
asyncdefgate_review_request(order: dict) -> bool:
phone = normalize_e164(order["customer"]["phone"])
ifawait is_opted_out(phone):
log_event("review_send_skipped_optout", order_id=order["id"])
returnFalse
allowed, _ = cooldown.can_send(phone)
ifnot allowed:
log_event("review_send_skipped_cooldown", order_id=order["id"])
returnFalsereturnTrue
Run this exact predicate at both schedule-time and fire-time. A contact who opts out during the 5-day refund buffer must not receive the scheduled send.
Error Handling
HTTP / Event
Podium Error
Root Cause
Action
400 Bad Request
invalid_phone
Phone number is not E.164 or unreachable
Skip — log and continue. Do not retry.
409 Conflict
cooldown_violation
Podium-side cooldown rejected the send
Trust Podium — log and skip. Do not bypass.
429 Too Many Requests
rate_limited
Campaign rate limit hit
Honor Retry-After. See podium-rate-limit-survival.
review_invitation.failed (webhook)
carrier_filtered
Carrier (T-Mobile/Verizon) rejected the SMS
Roll back cooldown; flag the phone for manual review.
review_invitation.failed (webhook)
recipient_optout
Customer replied STOP to a prior message
Mark podium_keyword_optout=true on the contact, propagate to opt-out source-of-truth.
review.received (webhook)
N/A
Customer left a review
Verify signature → classify sentiment → route.
Signature mismatch
N/A
Webhook signature verification failed
Return 401; do not process. Page on persistent mismatches (possible secret rotation drift).
Examples
Schedule a review request from a Shopify orders/fulfilled webhook
The bridge listens on :8787/shopify/orders-fulfilled and :8787/podium/review-received. Both endpoints verify their respective signatures before processing.
Output
Cooldown gate (Redis-backed) with phone-keyed last_contact_at and SETEX-driven expiry
Refund-race buffer with delayed-queue send + at-fire refund-status re-check
Failed-send outbox tracking sent → delivered | failed with cooldown rollback on failure
Idempotent review.received webhook handler with sentiment classification
Multi-platform routing selector with Google-fallback for unknown-platform customers
Unified opt-out predicate consulted at both schedule-time and fire-time
