A Plug router for processing incoming webhook notifications from YooKassa.

This module provides a pre-built handler that can parse and react to various payment and refund events sent by YooKassa. It includes built-in verification to ensure the authenticity of notifications by fetching the latest status from the YooKassa API and comparing it with the event data.

Security Features

The handler implements webhook verification by:

• Extracting only the id and event from incoming notifications
• Making authenticated API requests to YooKassa to fetch current payment/refund status
• Comparing the fetched status with the expected status from the event
• Only responding with 200 OK if verification succeeds

This prevents processing of spoofed or outdated webhook notifications.

Integration

This handler is a standard Plug and does not start its own web server. You are responsible for integrating it into your application's supervision tree with a web server like Plug.Cowboy or into your Phoenix application's router.

Example with Plug.Cowboy

When using Plug.Cowboy, this handler will respond to any POST request path that matches a route defined inside, like post "/webhook".

1. Add to your application.ex:

   children = [
     {Plug.Cowboy, scheme: :http, plug: Yookassa.WebhookHandler, options: [port: 8080]}
   ]

2. Configure YooKassa Webhook URL: https://your-ngrok-or-domain.com/webhook

Example with Phoenix Router

In Phoenix, you define the path explicitly.

1. Add to your router.ex:

   # lib/my_app_web/router.ex
   post "/yookassa_notifications", to: Yookassa.WebhookHandler

2. Configure YooKassa Webhook URL: https://your-domain.com/yookassa_notifications

Supported Events

This handler verifies and processes the following events:

• payment.succeeded
• payment.canceled
• payment.waiting_for_capture
• payment.pending
• refund.succeeded
• refund.canceled

Response Behavior

• 200 OK: Sent only when notification verification succeeds
• 400 Bad Request: Sent when verification fails or notification format is invalid
• 404 Not Found: Sent for requests to unsupported paths