Overview
Best-in-class webhook infrastructure supercharged to take your business to the next level.
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:
- Log in to your dashboard and click on Settings
- Navigate to Webhooks to add your webhook URL
- 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.
Updated about 1 year ago