> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mitu.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mitu.ai/_mcp/server.

# Configure webhooks

Webhooks notify your application when activity occurs in your Mitu account. You can use them to respond to completed payments, wallet activity, new customers, subscriptions and other changes without repeatedly checking the API.

Your webhook endpoint should verify each delivery before processing it and use the event ID to ensure that the same event is not processed more than once.

#### Create a webhook endpoint

Create an HTTPS endpoint in your application that can receive `POST` requests from Mitu.

In the Mitu dashboard, open **Webhooks** and add the URL of your endpoint. Your endpoint should be publicly accessible and return a successful response after it has accepted an event.

```text
https://example.com/webhooks/mitu
```

#### Choose the events you need

Select the events your application needs to receive. You do not need to subscribe to events that your application does not use.

| Resource      | Available events                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------------- |
| Payments      | `payment.completed`, `payment.failed`                                                                             |
| Payment links | `link.created`, `link.viewed`                                                                                     |
| Customers     | `customer.created`                                                                                                |
| Wallets       | `wallet.created`, `wallet.credited`, `wallet.debited`, `wallet.frozen`, `wallet.unfrozen`                         |
| Invoices      | `invoice.created`, `invoice.sent`, `invoice.viewed`, `invoice.paid`, `invoice.overdue`                            |
| Subscriptions | `plan.created`, `subscription.created`, `subscription.charged`, `subscription.past_due`, `subscription.cancelled` |
| Sessions      | `session.opened`, `session.closed`                                                                                |

Payment events describe payments received by your business. Wallet events describe activity on Agent Wallets that you have issued to your customers.

Choose events based on the actions your application needs to take. For example, an application that fulfils an order after payment may only need `payment.completed` for that workflow.

#### Store your webhook secret

Each webhook endpoint has its own signing secret. Store this secret securely in your application.

```text
whsec_…
```

The webhook secret is used to verify that webhook deliveries were sent by Mitu.

> **Use the correct secret**
>
> Your webhook secret is different from the signing secret used to verify requests sent to your API during agent interactions.
>
> Use the `whsec_…` secret to verify webhook deliveries. Use the `mps_…` signing secret when verifying signed requests sent to your API.

#### Verify each delivery

Webhook requests include a signature that your application should verify before processing the event.

```http
Content-Type: application/json
X-Mitu-Signature: v1,t=1788990420,sig=<hmac-sha256>
```

Verify the signature using the webhook secret associated with the endpoint that received the request. Perform verification before trusting or acting on any information in the event.

Keep the original request body available until verification is complete. Changing the body before verification can cause signature validation to fail.

Your implementation should also validate the timestamp included with the signature and use a timing safe comparison when comparing signatures.

Learn more about the verification process in [Webhooks](/platform/webhooks/overview).

#### Process the event

Every webhook follows a common event structure.

**`Webhook event`**

```json title="Webhook event"
{
  "event": "payment.completed",
  "event_id": "evt_a8f1zq5xkm2lcn6f",
  "event_created_at": "2026-09-09T14:22:57.003Z",
  "event_data": {}
}
```

| Field              | Description                                                                    |
| ------------------ | ------------------------------------------------------------------------------ |
| `event`            | Identifies the type of activity that occurred.                                 |
| `event_id`         | Uniquely identifies the event and can be used to prevent duplicate processing. |
| `event_created_at` | Identifies when the event was created.                                         |
| `event_data`       | Contains the information associated with the event.                            |

The contents of `event_data` depend on the event type. See [Events](/platform/webhooks/events) for the fields available for each event.

#### Prevent duplicate processing

Store the `event_id` after processing an event successfully. If your endpoint receives the same `event_id` again, acknowledge the request without applying the same change again.

This is important because webhook deliveries can be retried. Multiple deliveries with the same `event_id` represent the same event and should not create duplicate changes in your application.

Your endpoint should return a `2xx` response after it has successfully accepted the event. Responses outside the `2xx` range are treated as unsuccessful deliveries and may be retried.

Mitu attempts unsuccessful webhook deliveries up to five times with backoff. If all delivery attempts fail, you can inspect the delivery and resend it from the dashboard.

#### Test your endpoint

Use the **Test** action in the dashboard to send a webhook to your configured endpoint. Test deliveries use the same delivery process as other webhook events and appear in your webhook logs.

Check that your endpoint receives the request, verifies the signature, processes the event and returns a successful response.

You can use the webhook logs to inspect delivery attempts and troubleshoot unsuccessful responses before relying on the endpoint in production.

## Common webhook events

The events you handle depend on the products you use and how your application responds to activity.

| Event               | Common use                                                                               |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `payment.completed` | Confirm that a payment has completed and update the corresponding record in your system. |
| `payment.failed`    | Record an unsuccessful payment attempt and determine whether another attempt is needed.  |
| `wallet.credited`   | Update your application when funds are added to a customer's Agent Wallet.               |
| `wallet.debited`    | Update your application when funds are spent from a customer's Agent Wallet.             |
| `customer.created`  | Associate a newly created customer with the corresponding customer in your system.       |

For the complete list of events and their payloads, see [Events](/platform/webhooks/events).

## Continue building

Your application can now receive changes as they happen. Continue with the detailed webhook documentation or move on to the integration guide that matches what you want to build.

#### [Events](/platform/webhooks/events)

Review the events available for each resource and the data included with them.

#### [Webhooks](/platform/webhooks/overview)

Learn more about webhook verification, delivery behaviour and retries.

#### [Connect to AI agents](/guides/integration-guides/connect-to-ai-agents)

Connect your existing products, services and APIs to supported AI clients.

#### [Accept payments from agents](/guides/integration-guides/accept-payment-from-agents)

Let AI agents pay while completing actions through your product.