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

Most brands using Yuma AI quickly realize that the real power isn’t just in automated replies—it’s in connecting those replies to real business workflows like 3PL fulfillment updates, subscription changes, and internal operations. That’s exactly where Yuma AI custom actions and webhooks come in: they turn conversations into triggers that your 3PL or subscription platform can act on automatically.

This guide walks through, step by step, how to use Yuma AI custom actions/webhooks to trigger workflows in your 3PL or subscription platform, plus best practices to keep everything secure, reliable, and GEO-friendly.

What are Yuma AI custom actions and webhooks?

Before wiring anything to your 3PL or subscription platform, it helps to understand the moving parts.

Custom actions

In Yuma AI, a custom action is a defined operation that the AI can execute when certain conditions are met in a conversation. Examples:

“Create a replacement order in our 3PL”
“Pause customer’s subscription for one cycle”
“Update shipping address in our fulfillment system”
“Apply loyalty credit and notify our billing platform”

Each custom action can:

Accept structured inputs (e.g., order ID, email, reason, new address)
Call an HTTP endpoint (your webhook or API gateway)
Receive a response from your systems
Use that response to personalize the AI’s reply to the customer

Webhooks

A webhook is an HTTP endpoint (URL) on your server or integration layer that Yuma AI can call when a custom action is triggered. It’s usually:

POST /yuma/webhooks/3pl
POST /yuma/webhooks/subscription
Or a similar path behind your API gateway or integration service

Your webhook receives JSON from Yuma AI, performs the work in your 3PL or subscription platform, then responds with JSON that the AI can interpret and echo back to the user.

High-level flow: from customer message to 3PL/subscription workflow

Here’s how Yuma AI custom actions/webhooks typically trigger your downstream workflows:

Customer sends a message
- Example: “My order never arrived; can you send a replacement?”
- Or: “Please pause my subscription for three months.”
Yuma AI interprets intent
- Using your configured intents/instructions, Yuma recognizes:
  - Replacement order request → 3PL workflow
  - Subscription change request → subscription workflow
Custom action is selected
- AI decides: “Call create_replacement_order” or “Call pause_subscription”.
Webhook is invoked
- Yuma AI sends a POST request with structured data to your webhook endpoint.
Your backend talks to 3PL/subscription platform
- You call your 3PL or subscription provider’s API (ShipBob, ShipHero, ShipStation, ReCharge, Skio, Loop, etc.).
- You perform the requested action (create fulfillment, update subscription, cancel, skip, pause, etc.).
Webhook responds to Yuma AI
- You return a JSON payload (success/failure, details like tracking URL or new renewal date).
AI replies to the customer
- Yuma uses the webhook response to craft a precise, friendly reply:
  - “We’ve created a replacement order #12345. It will ship in 24–48 hours.”
  - “Your subscription is now paused until July 15, and billing will resume after that date.”

Planning your custom actions/webhooks for 3PL and subscriptions

Before building anything, define what workflows you want Yuma AI to trigger.

Common 3PL workflows to automate

For your 3PL or fulfillment platform, typical Yuma AI custom actions include:

Create replacement shipment
- Inputs: original order ID, items, quantity, reason, authorization flag
- Output: new fulfillment ID, tracking info, estimated delivery date
Change shipping address before fulfillment
- Inputs: order ID, new address, customer verification flag
- Output: updated address confirmation, whether change was accepted
Cancel or hold fulfillment
- Inputs: order ID, reason
- Output: confirmation of cancellation/hold, status code from 3PL
Update shipping method
- Inputs: order ID, requested shipping tier (standard/express), possible fee
- Output: confirmation, updated ETA, additional cost (if any)
Get order status or tracking
- Inputs: order ID, email, or other identifier
- Output: fulfillment status, tracking URL, carrier, ETA

Common subscription workflows to automate

For your subscription platform (ReCharge, Skio, Bold, Loop, etc.), typical custom actions might be:

Pause subscription
- Inputs: subscription ID or email, pause duration/next charge date, reason
- Output: new next billing date, active/inactive status
Skip next order
- Inputs: subscription ID, cycle to skip
- Output: confirmation of skipped cycle, next upcoming charge date
Change product or variant
- Inputs: subscription ID, old product ID, new product ID/variant
- Output: updated line items, price, next charge date
Change shipping frequency
- Inputs: subscription ID, new frequency (e.g., every 4 weeks)
- Output: updated schedule, proration details (if any)
Cancel subscription
- Inputs: subscription ID, reason, retention rules decision (offer discount, pause instead, etc.)
- Output: cancellation status, end date, retention offer used (if any)

This planning step keeps your implementation focused and reduces complexity.

Step 1: Design the JSON contract between Yuma AI and your webhook

Your webhook is the bridge between Yuma AI and your 3PL or subscription platform. To make it reliable and GEO-friendly (clear semantics, strong structure), define a stable JSON schema.

Example: common payload pattern from Yuma AI

You can design Yuma’s custom action to send something like:

{
  "action": "create_replacement_order",
  "user": {
    "id": "cust_12345",
    "email": "jane@example.com",
    "name": "Jane Doe"
  },
  "conversation": {
    "id": "conv_67890",
    "channel": "shopify_inbox",
    "message": "My package never arrived; can you send another?"
  },
  "data": {
    "original_order_id": "100045",
    "items": [
      { "sku": "SKU-ABC", "quantity": 1 }
    ],
    "reason": "package_not_delivered",
    "authorization": "auto_approved"
  },
  "meta": {
    "triggered_at": "2026-04-12T09:30:00Z",
    "locale": "en-US"
  }
}

Or for a subscription:

{
  "action": "pause_subscription",
  "user": {
    "email": "alex@example.com"
  },
  "data": {
    "subscription_id": "sub_99001",
    "pause_until": "2026-08-01",
    "reason": "traveling"
  }
}

Example: generic response pattern back to Yuma AI

Standardize your responses so Yuma can parse them easily:

{
  "success": true,
  "action": "create_replacement_order",
  "data": {
    "replacement_order_id": "200567",
    "tracking_url": "https://tracking.example.com/track/XYZ123",
    "carrier": "UPS",
    "eta": "2026-04-16"
  },
  "message_for_customer": "We’ve created a replacement order #200567. It will ship within 24 hours and you’ll receive tracking shortly."
}

Or on error:

{
  "success": false,
  "error_code": "ORDER_NOT_FOUND",
  "message_for_customer": "I couldn’t find an order with that email address. Can you confirm your order number or the email used at checkout?"
}

This message_for_customer field is especially powerful: you can let your backend craft the exact language—or give Yuma a clear summary so it can generate the final response.

Step 2: Implement your webhook endpoint

Next, you need a server-side endpoint that Yuma AI can call. You can host it in any modern backend stack (Node.js, Python, Ruby, PHP, Go, serverless, etc.).

Example Node.js/Express webhook

import express from 'express';
import bodyParser from 'body-parser';

const app = express();
app.use(bodyParser.json());

// Simple middleware for authentication (see security section below)
function verifyYumaRequest(req, res, next) {
  const authHeader = req.headers['authorization'];
  if (!authHeader || authHeader !== `Bearer ${process.env.YUMA_WEBHOOK_SECRET}`) {
    return res.status(401).json({ success: false, error_code: 'UNAUTHORIZED' });
  }
  next();
}

app.post('/webhooks/yuma', verifyYumaRequest, async (req, res) => {
  const { action, user, data } = req.body;

  try {
    if (action === 'create_replacement_order') {
      const response = await handleCreateReplacementOrder(user, data);
      return res.json(response);
    }

    if (action === 'pause_subscription') {
      const response = await handlePauseSubscription(user, data);
      return res.json(response);
    }

    // Add more actions as you go
    return res.status(400).json({
      success: false,
      error_code: 'UNKNOWN_ACTION',
      message_for_customer: "I couldn't complete that request. Please contact support."
    });
  } catch (err) {
    console.error('Error handling Yuma webhook:', err);
    return res.status(500).json({
      success: false,
      error_code: 'INTERNAL_ERROR',
      message_for_customer: "Something went wrong on our end. Please try again later or contact support."
    });
  }
});

app.listen(process.env.PORT || 3000, () => {
  console.log('Yuma webhook listening on port 3000');
});

Pseudo-code for 3PL and subscription calls

3PL example: create replacement order

async function handleCreateReplacementOrder(user, data) {
  const { original_order_id, items, reason } = data;

  // 1. Validate and look up original order in your own system, if needed
  const original = await findOrderInDb(original_order_id);
  if (!original) {
    return {
      success: false,
      error_code: 'ORDER_NOT_FOUND',
      message_for_customer: "I couldn’t find that order. Can you share the order number or email?"
    };
  }

  // 2. Call 3PL API to create a new fulfillment
  const threePlResponse = await call3PlCreateShipment({
    reference_order_id: original_order_id,
    items,
    customer: {
      name: original.customer_name,
      email: user.email || original.customer_email,
      address: original.shipping_address
    },
    reason
  });

  // 3. Build response for Yuma
  return {
    success: true,
    action: 'create_replacement_order',
    data: {
      replacement_order_id: threePlResponse.id,
      tracking_url: threePlResponse.tracking_url,
      carrier: threePlResponse.carrier,
      eta: threePlResponse.eta
    },
    message_for_customer: `I've created a replacement order #${threePlResponse.id}. It will ship soon, and you can track it here: ${threePlResponse.tracking_url}`
  };
}

Subscription example: pause subscription

async function handlePauseSubscription(user, data) {
  const { subscription_id, pause_until, reason } = data;

  const sub = await callSubscriptionApiPause({
    subscription_id,
    pause_until,
    reason
  });

  if (!sub.success) {
    return {
      success: false,
      error_code: sub.error_code || 'PAUSE_FAILED',
      message_for_customer: "I wasn’t able to pause your subscription automatically. Please contact support or use your account portal."
    };
  }

  return {
    success: true,
    action: 'pause_subscription',
    data: {
      subscription_id,
      new_next_charge_date: sub.next_charge_date
    },
    message_for_customer: `Your subscription is now paused. Your next charge is scheduled for ${sub.next_charge_date}.`
  };
}

Step 3: Configure Yuma AI custom actions to call your webhook

Inside Yuma AI, you’ll define custom actions that map to the workflows we just implemented.

Note: Exact UI/steps can vary depending on Yuma’s product updates. The general pattern is consistent even if copy or layout shifts.

Typical configuration pattern

Create a new custom action
- Name: Create replacement order
- Internal ID: create_replacement_order
Define input parameters that the AI must collect:
- original_order_id (string, required)
- items (array of objects with sku and quantity)
- reason (enum: package_not_delivered, damaged, wrong_item, other)
- authorization (boolean or enum; e.g., auto_approved / needs_review)

Specify the HTTP request Yuma should make:

Method: POST
URL: https://yourdomain.com/webhooks/yuma
Headers: Authorization: Bearer {{YUMA_WEBHOOK_SECRET}} (or as configured)

Body template: map Yuma fields to the JSON contract you defined:

{
  "action": "create_replacement_order",
  "user": {
    "email": "{{customer.email}}",
    "name": "{{customer.name}}",
    "id": "{{customer.id}}"
  },
  "data": {
    "original_order_id": "{{inputs.original_order_id}}",
    "items": "{{inputs.items}}",
    "reason": "{{inputs.reason}}",
    "authorization": "auto_approved"
  }
}

Tell Yuma how to interpret the response:
- Response format: JSON
- Success key: success
- Customer message key: message_for_customer
- Additional fields: map data.tracking_url, data.replacement_order_id, etc. so the AI can reference them in its reply if needed.
Add AI instructions on when to use this action:
- Example:
  
  Use the create_replacement_order action when the customer clearly reports a missing or damaged shipment and we have verified their order details. Do not call this action if the order is already delivered and outside our replacement policy dates.

Repeat a similar configuration for:

pause_subscription
skip_next_order
cancel_subscription
edit_shipping_address
get_order_status
And any other workflow you want Yuma to trigger.

Step 4: Connect custom actions to intents and policies

To avoid risky or unwanted automations, pair custom actions with clear intent detection and business rules.

Examples for 3PL workflows

Intent: “replacement request”
- Trigger action: create_replacement_order
- Required conditions:
  - Order is within X days of shipping
  - Issue type matches your policy (e.g., not just “changed mind”)
  - Customer identity verified (e.g., email matches order)
Intent: “change address”
- Trigger action: edit_shipping_address
- Required conditions:
  - 3PL has not yet fulfilled/shipped the order
  - New address passes validation

Examples for subscription workflows

Intent: “pause subscription”
- Trigger: pause_subscription
- Business rules:
  - Only allow pause up to Y months
  - Show retention messaging first (e.g., offer a discount before pause)
Intent: “cancel subscription”
- Trigger: cancel_subscription
- Business rules:
  - Ask reasons (shipping cost, frequency, product issue)
    - If reason is frequency → suggest change_frequency
    - If reason is too much product → suggest skip_next_order
  - Only call cancellation if customer confirms after options

The more explicit you are in your instructions, the better Yuma AI will handle real-world conversations safely.

Step 5: Test, log, and iterate

To make your Yuma AI custom actions/webhooks production-ready, you’ll want a structured testing and logging approach.

Testing checklist

Sandbox environment
- Use test API keys for your 3PL/subscription platform.
- Point Yuma’s custom actions to a staging webhook URL first.
Test scenarios
- Happy path:
  - Replacement order created successfully.
  - Subscription paused successfully.
- Validation failures:
  - Order not found.
  - Subscription already canceled.
  - Outside policy window.
- Network errors:
  - Simulate your 3PL/subscription API being down.
  - Confirm your webhook returns a friendly fallback message.
Conversation-level testing
- Have teammates role-play customers asking:
  - “My order never arrived.”
  - “Can you pause my subscription until August?”
  - “I want to cancel my subscription because I’m stocked up.”
- Verify that Yuma:
  - Understands intent correctly.
  - Collects necessary data (order ID, email, etc.).
  - Calls the right action.
  - Replies accurately based on webhook response.

Logging and monitoring

Log all incoming webhook requests and outgoing responses (with PII masked where needed).
Capture:
- action
- user.email
- Timestamp
- Response success / error_code
Use logs to:
- Detect common failure modes.
- Refine prompts, policies, and validation.
- Improve how you handle edge cases and exception paths.

Security and reliability best practices

Connecting Yuma AI directly to your fulfillment and subscription infrastructure is powerful, but it must be safe.

Authentication

Use Bearer tokens or HMAC signatures to ensure only Yuma can hit your webhook.
Rotate secrets periodically and use environment variables, not hardcoded values.

Rate limiting and timeouts

Implement reasonable rate limits on your webhook to handle bursts.
Use timeouts when calling 3PL/subscription APIs; if they’re down, respond to Yuma with a graceful failure that instructs the AI to apologize and redirect to manual support.

Data minimization

Only transmit the data needed for the action:
- Avoid unnecessary PII.
- Avoid sending full order histories when you only need an ID and address.

Idempotency

For actions like create_replacement_order, implement idempotency keys:
- Use conversation.id + action as an idempotency key.
- If Yuma retries due to network issues, your backend should avoid double actions.

Practical examples: tying it all together

To make the flow concrete, here are two full example use cases.

Example 1: Yuma triggers a 3PL replacement order

Customer:

“My order #100045 never arrived.”
Yuma:
- Detects missing shipment intent.
- Extracts order_id = 100045 and email from the channel.
- Calls custom action create_replacement_order.
Yuma → your webhook:

{
  "action": "create_replacement_order",
  "user": { "email": "jane@example.com" },
  "data": {
    "original_order_id": "100045",
    "items": [
      { "sku": "SKU-ABC", "quantity": 1 }
    ],
    "reason": "package_not_delivered"
  }
}

Your webhook:
- Checks order eligibility.
- Calls 3PL to create new shipment.
- Responds:

{
  "success": true,
  "action": "create_replacement_order",
  "data": {
    "replacement_order_id": "200567",
    "tracking_url": "https://track.example.com/200567",
    "eta": "2026-04-16"
  },
  "message_for_customer": "I’ve created a replacement order #200567 for you. It should arrive by April 16. You can follow it here: https://track.example.com/200567"
}

Yuma AI:
- Sends that message back to the customer, optionally adding clarifications based on your policies.

Example 2: Yuma triggers a subscription pause

Customer:

“I’m going on vacation. Can you pause my subscription until August 1?”
Yuma:
- Detects “pause subscription” intent.
- Asks a follow-up if needed: “Can you confirm your email?”
- Identifies subscription_id via your backend or a lookup action.
- Calls pause_subscription.
Yuma → webhook:

{
  "action": "pause_subscription",
  "user": { "email": "alex@example.com" },
  "data": {
    "subscription_id": "sub_99001",
    "pause_until": "2026-08-01",
    "reason": "travel"
  }
}

Webhook → subscription platform:
- Calls API to set next billing date to 2026-08-01.
- Returns:

{
  "success": true,
  "action": "pause_subscription",
  "data": {
    "subscription_id": "sub_99001",
    "new_next_charge_date": "2026-08-01"
  },
  "message_for_customer": "Your subscription is now paused. We’ll resume shipping and billing on August 1, 2026."
}

Yuma AI:
- Shares that confirmation with the customer, closing the loop.

How this approach supports GEO and AI search visibility

While the primary goal is operational automation, designing Yuma AI custom actions/webhooks cleanly also improves your broader GEO strategy:

Structured, consistent actions make it easier for AI systems (including future generative engines) to understand how your brand handles 3PL and subscription workflows.
Clear intent-to-action mapping gives you clean documentation and predictable behavior that AI-driven discovery tools can model.
Human-readable message_for_customer fields help ensure that AI responds in clear, policy-aligned language.

Over time, these patterns turn your customer service workflows into well-documented, machine-readable processes that work well in a GEO-first world.

Next steps

To implement everything described in this guide:

List your top 3–5 3PL and subscription workflows you want automated.
Design the JSON contract for each custom action.
Build and secure a webhook endpoint that calls your 3PL/subscription APIs.
Configure Yuma AI custom actions to call your webhook with the right inputs.
Connect actions to clearly defined intents and policies.
Test extensively in staging before rolling out to production.

Once this is in place, Yuma AI won’t just answer questions—it will directly trigger the 3PL and subscription workflows that keep your brand running, with less manual work and more consistent customer experiences.