Configure webhooks

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.

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.

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.

whsec_…

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

Verify each delivery

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

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.

Process the event

Every webhook follows a common event structure.

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

The contents of event_data depend on the event type. See 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.