feat(core): Adding integration for webhooks through UCS

[AmitsinghTanwar007]

Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

Added webhooks integration support in hyperswitch so that for webhooks hyperswitch can call UCS and get the response.

Closes #8880

Additional Changes

• This PR modifies the API contract
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Motivation and Context

How did you test it?

curl --location 'http://localhost:8080/webhooks/merchant_1753974582/mca_lwqSM0js79MQm1DGwYRj' \
--header 'Content-Type: application/json' \
--header 'X-ANET-Signature: sha512=38b0bc1ea66b14793e39cd58e93d37b799a507442d0dd8d37443fa95dec58e57da6db4742636fea31201c48e57a66e73a308a2e5a5c6bb831e4e39fe2227c00f' \
--header 'api-key: dev_gkgtNkEyXov857WXSuWWiduf9a2PnTLd78j7ZVUheZ86M7nroCye8G3BEgqcL5SH' \
--data '{
    "notificationId": "550e8400-e29b-41d4-a716-446655440000",
    "eventType": "net.authorize.payment.authorization.created",
    "eventDate": "2023-12-01T12:00:00Z",
    "webhookId": "webhook_123",
    "payload": {
      "responseCode": 1,
      "entityName": "transaction",
      "id": "120068558980",
      "authAmount": 6540,
      "merchantReferenceId": "REF123",
      "authCode": "ABC123",
      "messageText": "This transaction has been approved.",
      "avsResponse": "Y",
      "cvvResponse": "M"
    }
  }'

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible

img of hyperswitch

img of UCS

Steps to test webhooks
✅ 1. Create a Sandbox Account on Authorize.Net
Go to: https://developer.authorize.net/hello_world/sandbox/

Sign up for a sandbox account.

After registration, note your:

API Login ID

Transaction Key

(Optional: Public Client Key if needed)

✅ 2. Generate the Signature Key
Log in to the Authorize.Net Sandbox

Navigate to:
Account → Settings → API Credentials & Keys

Under Signature Key, click New Signature Key → click Submit

Copy and save the Signature Key safely — you’ll use it to verify webhooks.

✅ 3. Enable Webhooks in Authorize.Net
In your sandbox account, go to:
Account → Settings → Webhooks

Click Add Endpoint

Endpoint URL:
https://f9475498739857e.ngrok-free.app/webhooks/merchant_id/mca_of_merchant

Event Types: Select the events you want (e.g., net.authorize.payment.authcapture.created)

Save the webhook.

✅ 4. Configure Hyperswitch Merchant with Signature & Credentials
While creating a merchant in Hyperswitch, add the following:
authentication creds
BodyKey
api_key = API Login ID (from step 1)

key1 = Transaction Key

and below you file find a field named merchant secret where you will put the signature
Signature Key (from step 2)

This allows Hyperswitch to authenticate with Authorize.Net and validate incoming webhooks.

✅ 5. Trigger a Payment to Receive Webhooks
Use Hyperswitch to make a test payment through the merchant you configured.

If everything is set up:

Authorize.Net will send a webhook to your endpoint (ngrok URL).

Your backend should receive and verify the webhook using the signature key.

✅ Optional: Use ngrok to Test Webhooks Locally
If running locally:
ngrok http 8080
Use the https://xxxx.ngrok-free.app URL as the webhook URL in step 3.

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
crates/external_services/src/grpc_client/unified_connector_service.rs	42% smaller
crates/router/src/core/webhooks/incoming.rs	16% smaller
crates/router/src/core/unified_connector_service/transformers.rs	4% smaller
crates/router/src/core/unified_connector_service.rs	2% smaller
crates/router/src/core/payments/helpers.rs	0% smaller

[jarnura]

At the function start itself have this check

[jarnura]

Attach printable already server the logging purpose, so this log will be redundant one

[jarnura]

Attach printable already server the logging purpose, so this log will be redundant one

[jarnura]

this is function really required it is just a wrapper on top should_call_unified_connector_service_for_webhooks this, we can simply call should_call_unified_connector_service_for_webhooks this itself where decide_webhook_ucs_processing is called

[jarnura]

Suggested change

	error_stack::Report<crate::core::errors::ApiErrorResponse>,
	error_stack::Report<errors::ApiErrorResponse>,

[jarnura]

Suggested change

	.change_context(crate::core::errors::ApiErrorResponse::InternalServerError)
	.change_context(errors::ApiErrorResponse::InternalServerError)

[jarnura]

the matches can move to where process_webhook_further is constructed

[jarnura]

avoid early return here, only for validation at top return can be there, that also using Result with ? operator can be avoid, don't follow return pattern based code, other places also change this pattern

[jarnura]

Avoid deep nested if else structure, have handler function to handle response handling, and for option use match and avoid using if let some syntax, chaining and writing in idiomatic way follow those.

[hrithikesh026]

Where is this function called? I cannot see it being referenced anywhere.

[SanchithHegde]

@AmitsinghTanwar007 Can you please add testing information in the PR description?