Skip to main content

​
Setting Up the Webhook Endpoint

The KarmaGo package provides a simple way to handle payment gateway webhooks securely and efficiently. The payments.KarmaPayWebhook() function integrates with GoFiber to validate incoming webhook requests and execute a custom action function when the webhook is verified.

​
Prerequisites

Before setting up the webhook endpoint, ensure:
  1. Environment Variables are Properly Configured Set the KARMAPAY_WEBHOOK variable in your .env file. For example: 
    KARMAPAY_WEBHOOK=https://yourdomain.com/webhook
  2. Webhook Secret The WEBHOOK_SECRET variable must be configured in your environment for secure webhook validation. For example: 
    WEBHOOK_SECRET=my-secure-webhook-secret
  3. Webhook URL Registered with Payment Gateway Ensure that the KARMAPAY_WEBHOOK URL is registered with the payment gateway you’re using (e.g., Razorpay, Stripe, etc.).

​
Creating the Webhook Endpoint

The payments.KarmaPayWebhook() function takes a custom action function as input. This action function is executed when the webhook is verified successfully.

​
Example Code

Here’s how to set up the webhook endpoint in your Go application: 
package main

import (
	"github.com/gofiber/fiber/v2"
	"github.com/MelloB1989/karma/payments"
	"yourproject/bookings"
)

// Define the action function for handling webhook data
func WebhookHandler(data map[string]string) error {
	uid := data["uid"]
	bookingId := data["koid"]

	// Retrieve the booking by ID and user ID
	booking, err := bookings.GetBookingByIdAndUID(bookingId, uid)
	if err != nil || booking == nil {
		return err
	}

	// Update the booking status
	booking.Status = "CONFIRMED"
	err = bookings.UpdateBooking(booking)
	if err != nil {
		return err
	}

	return nil
}

func main() {
	// Initialize Fiber app
	app := fiber.New()

	// Define the webhook route
	app.Post("/webhook", payments.KarmaPayWebhook(WebhookHandler))

	// Start the server
	if err := app.Listen(":3000"); err != nil {
		panic(err)
	}
}

​
How It Works

  1. Webhook Route Handling
    • The /webhook route listens for POST requests from the payment gateway.
    • This should match the URL you set in the KARMAPAY_WEBHOOK environment variable.
  2. Verification and Execution
    • The KarmaPayWebhook() function validates the incoming webhook request using the WEBHOOK_SECRET.
    • If the request is verified successfully, the custom action function (WebhookHandler in this example) is executed.
  3. Automatic Parameters
    • The webhook payload automatically includes a koid field (the Order ID) added by the KarmaPay service.
    • You can use koid to retrieve the relevant booking or order.
  4. Custom Action Function
    • The WebhookHandler function takes a map[string]string containing the webhook data.
    • You can define custom logic, such as updating booking statuses or triggering other workflows, based on the webhook data.

​
Example .env File

Here’s an example .env configuration for the webhook: 
KARMAPAY_WEBHOOK=https://yourdomain.com/webhook
WEBHOOK_SECRET=my-secure-webhook-secret

​
Testing the Webhook

  1. Simulate a Payment Use the CreatePaymentOrder function to generate a payment URL and complete a transaction.
  2. Trigger the Webhook The payment gateway sends a POST request to the /webhook endpoint after the payment is completed.
  3. Verify the Results Check that the WebhookHandler function executes correctly and performs the desired action (e.g., updating the booking status).

​
Notes for Beginners

  • Webhook Verification: The KarmaPayWebhook function automatically verifies the webhook signature using WEBHOOK_SECRET. You don’t need to write custom verification logic.
  • Action Function Flexibility: The action function can perform any custom operation you define, as long as it matches the signature func(data map[string]string) error.

​
Troubleshooting

  • Webhook Not Triggering: Ensure the payment gateway has the correct URL and is configured to send webhook events.
  • Signature Mismatch: Verify that WEBHOOK_SECRET matches the secret configured in the payment gateway.
  • Action Function Errors: Check the logs for errors in the custom action function.
With this setup, your application will be able to handle and process webhook events from KarmaPay securely and efficiently.