Seamlessly Automate Payments: Integrating Stripe Webhooks with .do Actions

Payment processing is the lifeblood of any online business, but what happens after a charge succeeds is just as critical. Updating user accounts, provisioning services, sending receipts, and logging transactions are all essential tasks that can quickly become a complex, brittle web of custom code.

Stripe webhooks provide the real-time event notifications you need, but how do you handle them in a way that is reliable, scalable, and easy to maintain?

Enter the Atomic Action.

On the .do platform, we believe that complex processes are built from simple, powerful building blocks. By treating each step of your post-payment logic as a discrete, self-contained action, you can build incredibly robust agentic workflows. In this post, we'll walk you through integrating Stripe webhooks with .do by creating a reusable action to handle successful payments.

Why Atomic Actions are a Perfect Match for Webhooks

Webhooks are fundamentally event-driven. An event happens, and a notification is sent. An atomic action is the perfect "verb" to respond to that event "noun."

• Single Responsibility: An action is designed to do one thing and do it well. An action like updateUserSubscription is clear, focused, and easy to understand. This is a perfect fit for a webhook handler, which should execute a specific piece of business logic in response to a specific event like charge.succeeded.
• Reliability & Idempotency: Webhook providers like Stripe may occasionally send the same event more than once. Your handler logic must be idempotent—meaning running it multiple times with the same input has the same effect as running it once. Actions, as isolated units of logic, are easy to design this way, preventing duplicate database entries or annoying your users with multiple "welcome" emails.
• Reusability: The beauty of "business as code." The same provisionNewService action can be triggered by a Stripe webhook, an admin clicking a button in a dashboard, or a customer support agent running a command. Once defined, your core business logic becomes a programmable, reusable asset.
• Testability: How do you test a complex webhook handler? It's difficult. But testing a small, self-contained action with defined inputs and outputs is simple. This allows you to validate your business logic in isolation, ensuring it's rock-solid before it ever sees a live Stripe event.

Building a Reusable Action for Successful Stripe Payments

Let's build a practical example. When a charge.succeeded event occurs in Stripe, we want to:

1. Find the user in our database via their Stripe Customer ID.
2. Update their account to grant them access to premium features.
3. Log the transaction for auditing purposes.

Here’s how you would define this as an atomic action on the .do platform.

import { Action } from '@do-co/agent';
// Assume db and auditLog are your imported services
import { db, auditLog, emailService } from './services';

// Define a new atomic action to handle a successful payment
const handleSuccessfulPayment = new Action('stripe-handle-successful-payment', {
  title: 'Handle Successful Stripe Payment',
  description: 'Updates a user account after a charge.succeeded event.',
  input: {
    // We expect the customer and charge IDs from the Stripe event object
    customerId: { type: 'string', required: true },
    chargeId: { type: 'string', required: true },
  },
  async handler({ customerId, chargeId }) {
    // 1. Find the user in our local database
    console.log(`Looking up user for Stripe customer: ${customerId}`);
    const user = await db.findUserByStripeId(customerId);

    if (!user) {
      // Handling edge cases is crucial for robust automation.
      // The .do platform can log this failure for review.
      throw new Error(`User not found for Stripe customer ID: ${customerId}`);
    }

    // 2. Update user account (this step is idempotent)
    await db.updateUser(user.id, {
      subscriptionStatus: 'active',
      lastChargeId: chargeId,
    });
    console.log(`User ${user.id} subscription set to active.`);

    // 3. Log the transaction for auditing
    await auditLog.create({
      userId: user.id,
      action: 'payment_succeeded',
      details: { chargeId, customerId }
    });
    
    // Pro-tip: You can even chain another action!
    // await sendPaymentReceiptEmail.run({ to: user.email, chargeId });

    return { success: true, userId: user.id };
  },
});

// To test or run this action manually:
// const result = await handleSuccessfulPayment.run({
//   customerId: 'cus_xxxxxxxxxxxxxx',
//   chargeId: 'ch_xxxxxxxxxxxxxx',
// });
// console.log(result);

Triggering the Action from a Webhook Endpoint

With our business logic perfectly encapsulated in the handleSuccessfulPayment action, connecting it to the outside world is trivial. You simply need a thin API layer (like an Express route or a serverless function) to receive the webhook, validate it, and execute the action.

// Example using an Express.js server

app.post('/webhooks/stripe', express.raw({type: 'application/json'}), async (req, res) => {
  let event;
  const signature = req.headers['stripe-signature'];

  // 1. CRITICAL: Verify the event came from Stripe
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    console.log(`⚠️  Webhook signature verification failed.`);
    return res.sendStatus(400);
  }

  // 2. Handle the 'charge.succeeded' event type
  if (event.type === 'charge.succeeded') {
    const charge = event.data.object;

    // 3. Execute our robust, testable, and reusable atomic action
    try {
      await handleSuccessfulPayment.run({
        customerId: charge.customer,
        chargeId: charge.id,
      });
    } catch (error) {
      // If the action fails, the .do platform can handle logging,
      // alerting, and even retry policies.
      console.error('Action execution failed:', error);
      return res.status(500).json({ error: 'Internal Server Error' });
    }
  }

  // 4. Acknowledge receipt of the event
  res.status(200).json({ received: true });
});

Notice the beautiful separation of concerns. The web server's only job is to handle HTTP communication and security validation. The real work—the core business logic—is delegated to the .do action.

From a Single Action to an Agentic Workflow

This is where the magic happens. Your handleSuccessfulPayment action is now a fundamental building block. You can use it to construct more powerful, intelligent, and automated agentic workflows.

Consider a "New Premium User Onboarding" workflow:

1. Trigger: Stripe charge.succeeded webhook arrives.
2. Execute Action: handleSuccessfulPayment.run(...)
3. Execute Action: provisionNewService.run({ userId: ... })
4. Execute Action: addToPremiumUsersCRM.run({ email: ... })
5. Execute Action: sendOnboardingDripCampaign.run({ userId: ... })

By composing simple atomic actions, you can orchestrate complex business processes that are easy to visualize, manage, and scale. Stop writing tangled, monolithic webhook handlers. Start building with the atomic unit of work.

Ready to transform your business logic into programmable building blocks? Get started on the .do platform and build your first agentic workflow today.

Frequently Asked Questions

What is an atomic action in the .do platform?
An atomic action is the smallest, indivisible unit of work in a workflow. It's a self-contained, executable task—like sending an email, querying a database, or calling an external API. Each action is designed to do one thing well.

How are actions different from workflows?
Actions are the individual steps, while workflows are the orchestration of multiple actions in a specific sequence or logic. You build complex workflows by composing simple, reusable actions together.

Can I create my own custom actions?
Absolutely. The .do SDK allows you to define custom actions with specific inputs, outputs, and business logic. This transforms your unique business operations into reusable, programmable building blocks for any workflow.