Overview

A webhook URL is an endpoint on your server where you can receive notifications about such events. When an event occurs, we'll make a POST request to that endpoint, with a JSON body containing the details about the event, including the type of event and the data associated with it.

Webhooks allow the Maplerad API to notify your application when certain events occur, eliminating the need for the application to poll the API for updates.

We notify you via your webhook endpoint for events such as a successful payment or a failed transaction.

To receive webhook notifications, you must first register the URL where the webhook should be sent and the triggering event. When the event occurs, the API will send an HTTP request containing the notification to the specified URL. If a valid HTTP response is not received, the API will retry up to 15 times on an exponential backoff schedule.

Webhook Security

When you add a webhook address to Maplerad, we will generate a secret key for that endpoint. We will then sign each request we make to the address with the secret so you can verify the webhook is actually being sent by Maplerad.

Webhook Structure

All webhook payloads follow the same basic structure

Enabling Webhook

Here's how to set up a webhook on your Maplerad account:

1. Log in to your dashboard and click on Settings
2. Navigate to Webhooks to add your webhook URL
3. Check all the boxes and save your settings

📘

Quick Tip

When testing, you can get an instant webhook URL by visiting webhook.site. This will allow you to inspect the received payload without having to write any code or set up a server.

Responding to webhooks

To acknowledge receipt of a webhook, your endpoint must return a 200 HTTP status code. Any other response codes, including 3xx codes, will be treated as a failure. We don't care about the response body or headers.

📘

Some web frameworks like Rails and Django automatically check that every POST request contains a CSRF token. This is a useful security feature that protects you and your users from cross-site request forgery.

However, for webhooks to work, you'll need to exempt the webhooks endpoint from CSRF protection (demonstrated in the examples below).

# In a Rails

class TransactionController < ApplicationController
    protect_from_forgery except: :webhook

    def webhook
        payload = params
        # It's a good idea to log all received events.
        Log.info payload
        # Do something (that doesn't take too long) with the payload and return 200
        head :ok
    end
end

Be Idempotent

Occasionally, we might send the same webhook event more than once. You should make your event processing idempotent (calling the webhook multiple times will have the same effect), so you don't end up giving a customer value multiple times.

One way of doing this is recording the events you've processed, and then checking if the status has changed before processing the duplicate event:

// in your webhook service
func (s *webhookService) IsTransactionProcessed(body types.MapleradWebhook) error {
  
  _, err := s.transactionService.FindByReference(body.ID)
  
  if err != nil {
    return errors.New("transaction has already been processed") 
  }
  
  return nil
  
}

// in your webhook handler 

func (wc *webhookController) MapleradWebhook(ctx *gin.Context) {
  var body types.MapleradWebhook
  
  if err := ctx.ShouldBindJSON(&body); err != nil {
		ctx.AbortWithStatus(http.StatusBadRequest)
		return
	}
  
  logger.Info("error: %v", &body)
  
  err := wc.webhookService.IsTransactionProcessed(body)
  
  if err != nil {
    // always a great idea to log outcomes
		logger.Error("error: %v", err.Error())
		ctx.AbortWithStatus(http.StatusOk)
		return
	}
  	// quickly return status
  	ctx.JSON(http.StatusOK)
  
  // perform long operations

	return
  
  
}

Always Re-query

Whenever you receive a webhook notification, before giving the customer value, where possible, you should call our verify API to verify the received details and ensure that the data returned has not been compromised.

Don't rely solely on webhooks

Have a backup strategy in place, in case your webhook endpoint fails. For instance, if your webhook endpoint is throwing server errors, you won't know about any new customer payments because webhook requests will fail.