How do we use Yuma AI custom actions/webhooks to trigger workflows in our 3PL or subscription platform?

Most ecommerce brands want their support inbox to do more than just answer questions. The real power comes when a customer message can automatically trigger actions in your 3PL, subscription, or logistics stack—without human intervention. That’s exactly where Yuma AI custom actions and webhooks come in.

In this guide, you’ll learn how to use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform, how to structure payloads, and how to keep everything secure and reliable.

What are Yuma AI custom actions and webhooks?

Before wiring anything into your 3PL or subscription system, it’s important to understand the building blocks.

Custom actions in Yuma AI

Custom actions are configurable operations that Yuma AI can trigger when certain conditions are met in a conversation. They let the AI go beyond replying and actually “do” something, for example:

Create or update an order in your 3PL
Pause/skip/cancel a subscription
Generate an RMA or return label
Change shipping method or address (within your policies)
Trigger internal workflows in tools like Zapier, Make, or n8n

These actions are usually powered by webhooks—HTTP requests sent to your own backend or to a third‑party integration endpoint.

Webhooks as the bridge to your 3PL or subscription platform

Webhooks allow Yuma AI to notify external systems when something happens in a conversation. When a customer asks for a change and Yuma AI decides it’s allowed, it can:

Call a webhook URL you configure
Send a JSON payload with all relevant data (order ID, customer email, request type, etc.)
Wait for the response to confirm success or failure
Use that response to inform the customer

This is how you connect Yuma AI to your 3PL, subscription apps like Recharge, Skio, Stay Ai, Loop, or your custom order/fulfilment stack.

Common 3PL and subscription workflows you can automate

To understand how to use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform, start from the use cases you want to cover.

1. Subscription management

Typical subscription actions:

Skip next shipment
Delay a renewal date
Change product in the subscription
Update shipping address for subscription orders
Cancel or reactivate a subscription

In each case, Yuma AI:

Detects a subscription-related intent from the conversation
Verifies needed details (customer identity, subscription ID, policy compliance)
Calls your subscription platform via webhook
Confirms the result back to the customer

2. 3PL and fulfilment operations

Common 3PL workflows:

Requesting an order cancellation before it ships
Changing shipping method (e.g., standard to express)
Updating shipping address for unfulfilled orders
Initiating a return or exchange
Triggering a reshipment or replacement order
Adding special notes or instructions to an open order

Here, the webhook will typically hit:

Your 3PL’s API directly (e.g., ShipBob, ShipHero, ShipStation, Whiplash)
Your own middleware/backend that then talks to the 3PL

3. Order and account information

You can also use custom actions/webhooks to fetch data:

Order status & tracking
Subscription status and next charge date
Loyalty points or rewards balance
Personalized discount or retention offers

Yuma AI calls your endpoint, gets the data, and uses it to craft a context-aware reply.

Designing your workflow: who does what?

To successfully use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform, define responsibilities clearly:

Yuma AI’s job
- Understand customer intent
- Validate required information
- Enforce your business rules (with your guidance)
- Call the correct custom action/webhook with structured data
- Present the result in natural language
Your backend or integration layer’s job
- Receive webhook calls securely
- Talk to your 3PL/subscription platform API
- Handle authentication, rate limits, and errors
- Return a clean, predictable response for Yuma AI

Often, it’s best not to call the 3PL or subscription platform directly from Yuma AI. Instead, create a small API layer of your own that:

Normalizes different providers’ APIs
Encapsulates your business logic
Is safer to expose to an AI agent

Step‑by‑step: setup for a 3PL workflow

Let’s walk through a concrete example: allowing Yuma AI to request an order cancellation with your 3PL.

Step 1: Map the business rules

Before creating any custom actions:

When is cancellation allowed?
- Only before the order is “picked” or “shipped”
- Only within X hours after order placement
Are there exceptions?
- Pre‑orders, limited drops, or final sale items
What should Yuma AI say if:
- Cancellation is allowed
- Cancellation is not allowed, but an alternative (store credit / reship) is possible
- The 3PL API is down or returns an error

Document these rules for your Yuma AI configuration and for your backend.

Step 2: Create a backend endpoint

Example endpoint: POST https://api.yourbrand.com/yuma/order/cancel

Responsibilities:

Accept JSON payload from Yuma AI
Validate signature or API key
Look up the order in your ecom platform (Shopify, etc.)
Check if cancellation is allowed
Call 3PL API to cancel the fulfilment if possible
Return a structured response

A simple response structure might be:

{
  "success": true,
  "status": "cancelled",
  "order_id": "12345",
  "reason": null,
  "message_for_customer": "Your order #12345 has been cancelled successfully and you’ll receive a full refund within 3–5 business days."
}

Or on failure:

{
  "success": false,
  "status": "already_fulfilled",
  "order_id": "12345",
  "reason": "Order has already shipped",
  "message_for_customer": "We’re not able to cancel order #12345 because it has already shipped. I can help you with a return once it arrives."
}

Step 3: Define the custom action / webhook in Yuma AI

In your Yuma AI configuration (exact UI may vary):

Action name: cancel_order_with_3pl
Trigger conditions: When the customer expresses clear intent to cancel an order and Yuma AI has:
- Customer email or user ID
- Order number
HTTP method: POST
URL: Your backend endpoint (e.g., https://api.yourbrand.com/yuma/order/cancel)
Headers:
- Content-Type: application/json
- Authorization: Bearer <your-internal-token> (if you secure it this way)
Request body template (variables filled in by Yuma AI):

{
  "customer_email": "{{customer.email}}",
  "customer_name": "{{customer.name}}",
  "order_id": "{{order.id}}",
  "order_number": "{{order.number}}",
  "user_message": "{{conversation.latest_message}}",
  "assistant_decision": "cancel_order",
  "source": "yuma_ai",
  "channel": "{{conversation.channel}}"
}

Response handling:
- On success: true, let Yuma AI use message_for_customer to reply
- On success: false, let Yuma AI either:
  - Use message_for_customer as is
  - Or combine it with your fallback policy messaging

Step 4: Teach Yuma AI how and when to use it

In your Yuma AI playbooks/instructions, you’ll want to:

Explain which requests should trigger cancel_order_with_3pl
Explain what to do when:
- Order ID is missing (ask for it, or offer an alternative verification path)
- Policy forbids cancellation
- The webhook returns an error

Give clear examples:

“If the customer provides an order number and asks to cancel, and the order appears to be within the cancellation window, call the cancel_order_with_3pl action.”
“If the order is older than X days or has a status indicating it has already shipped, do not call the action; instead, follow the returns policy instructions.”

Step‑by‑step: setup for a subscription platform workflow

Now let’s see how to use Yuma AI custom actions/webhooks to trigger workflows in your subscription platform, for example “skip next order.”

Step 1: Define the subscription scenarios

Common actions to implement:

skip_next_subscription_order
change_subscription_date
update_subscription_product
cancel_subscription

For each, define:

Required data (subscription ID, customer email, next charge date)
Guardrails (skip allowed X times per year, etc.)
Exact phrasing you want Yuma AI to use

Step 2: Create an integration endpoint

Example: POST https://api.yourbrand.com/yuma/subscription/skip

Your backend:

Looks up the customer by email or ID
Finds the subscription (in Recharge, Skio, etc.)
Validates skip rules (e.g., not too close to processing)
Calls the subscription API to skip the next order
Returns:

{
  "success": true,
  "subscription_id": "sub_789",
  "next_charge_date_before": "2026-04-10",
  "next_charge_date_after": "2026-05-10",
  "message_for_customer": "I’ve skipped your next subscription order. Your following charge will now be on May 10, 2026 instead of April 10, 2026."
}

On failure:

{
  "success": false,
  "reason": "too_close_to_renewal",
  "message_for_customer": "Your subscription is already processing for the upcoming shipment, so I can’t skip this one. I can help you skip the following month instead if you’d like."
}

Step 3: Configure the custom action in Yuma AI

Action name: skip_subscription_order
Trigger: Customer asks to “skip my next subscription,” “skip a month,” etc.
Request body template:

{
  "customer_email": "{{customer.email}}",
  "customer_name": "{{customer.name}}",
  "intent": "skip_next_subscription_order",
  "subscription_identifier": "{{subscription.id}}",
  "user_message": "{{conversation.latest_message}}"
}

Response usage: As with the 3PL example, Yuma AI uses the message_for_customer field and can add clarifications if needed.

Structuring webhook payloads for reliability

Whether you’re focusing on 3PL or subscriptions, your payload structure should be:

Consistent – Same shape for similar actions
Explicit – Include intent, IDs, and source
Extensible – Easy to add new fields later

A general pattern that works well:

{
  "source": "yuma_ai",
  "action": "cancel_order",
  "context": {
    "channel": "{{conversation.channel}}",
    "conversation_id": "{{conversation.id}}"
  },
  "customer": {
    "id": "{{customer.id}}",
    "email": "{{customer.email}}",
    "name": "{{customer.name}}"
  },
  "order": {
    "id": "{{order.id}}",
    "number": "{{order.number}}"
  },
  "subscription": {
    "id": "{{subscription.id}}"
  },
  "message": {
    "raw": "{{conversation.latest_message}}",
    "language": "{{conversation.language}}"
  },
  "metadata": {
    "assistant_version": "{{assistant.version}}"
  }
}

You won’t always need both order and subscription at once, but a pattern like this allows you to reuse code and add new actions quickly.

Security best practices

When you use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform, security is non‑negotiable.

1. Restrict and validate origin

Use a dedicated API token or OAuth between Yuma AI and your backend
Validate incoming requests:
- Check an Authorization header
- Optionally use HMAC signatures
- Limit access by IP or gateway if possible

2. Do not expose raw 3PL/subscription credentials

Yuma AI should only talk to your backend
Your backend owns credentials for:
- Shopify or your ecommerce platform
- 3PL
- Subscription platform
This gives you a single place to rotate keys and add logging

3. Enforce business rules on your backend too

Even if you teach Yuma AI your policies, always:

Re‑validate policy conditions in backend
Sanitize any user‑supplied text
Rate‑limit requests if needed

The backend is your last line of defense if instructions are misinterpreted.

Error handling and fallbacks

Things will occasionally fail—APIs time out, 3PLs go down, subscriptions are locked. Plan for:

1. Technical errors

When a webhook call:

Times out
Returns 5xx
Fails validation

Your backend should:

Return success: false
Provide a safe message_for_customer, like:

{
  "success": false,
  "reason": "technical_error",
  "message_for_customer": "I’m not able to complete this change right now due to a technical issue. I’ve created a ticket for our support team, and they’ll follow up with you via email."
}

Yuma AI can then:

Apologize briefly
Confirm escalation to human support
Avoid repeating the action until a human checks it

2. Business rule failures

When the platform responds with a business constraint:

Too late to cancel
Subscription locked near renewal
Action restricted by policy

Return a clear reason and customer message from your backend, so Yuma AI doesn’t have to guess.

Testing your 3PL and subscription webhooks

Before going live:

Use a staging environment
- Sandbox keys for your 3PL/subscription platform
- Test orders and test subscriptions
Simulate real conversations
- Ask to cancel, change address, skip, etc.
- Try edge cases (missing order ID, old orders, etc.)
Log every webhook call
- Request and response (sanitized)
- Timestamps and correlation IDs
- Flag errors / unexpected responses
Review AI behavior
- Ensure Yuma AI calls the right action
- Confirm messages align with your brand tone and policies

Expanding your automation over time

Once you have a few workflows working, it’s easier to add more ways to use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform:

Offer proactive reshipments when tracking shows “lost in transit”
Let customers modify bundles in subscription orders
Trigger internal alerts for VIP customers or high‑value orders
Start retention flows (discounts, swaps) instead of pure cancellations

Keep using the same core pattern:

Intent recognition by Yuma AI
Policy check + information gathering
Webhook to your backend
Backend talks to 3PL/subscription platform
Clean, human‑readable result returned to Yuma AI

Summary

To use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform:

Treat Yuma AI as the “front end” that understands the customer and initiates actions
Use webhooks to connect Yuma AI to your own backend, not directly to providers
Let your backend enforce policies and talk to your 3PL/subscription APIs
Design consistent payloads and responses, with message_for_customer fields
Prioritize security, error handling, and clear fallbacks to human support

With this architecture, every conversation becomes a potential automated workflow—turning your support inbox into a powerful operations layer for your 3PL and subscription stack.