Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your business with Rankbid.
Webhooks allow many custom automations for your business. For example, you can automatically deliver digital goods to the winning bidder when an auction ends by leveraging the information sent by Rankbid webhooks.

Setting up webhooks

To setup the Rankbid webhook, you need to have a URL that Rankbid can call. You can configure the webhook URL in your dashboard settings. You can also pick the events you want to listen for, such as when a new bid is placed on your auction.

Consuming webhooks

When your app receives a webhook request from Rankbid, check the eventType attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a conversation, message, etc.

Example webhook payload

{
    "eventType": "auction_started",
    "payload": {
        "auction": {
            "auctionId": "5119f4a6-2598-4229-9c36-658ac60eb5a3"
            // ...
        }
        // ...
    }
}

In the example above, an auction started, and the payload type is an auction.

Security

To know for sure that a webhook was sent by Rankbid instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-rankbid-secret, and you can verify this signature by using your webhook signing secret. The signing secret can be in your dashboard settings. There is currently no way to change the signing secret, so keep it safe. If you suspect that your secret has been compromised, please contact us so that we can generate a new secret for you.

Verifying a Rankbid webhook request

const signingSecret = request.headers['x-rankbid-secret'];

if (signingSecret === process.env.RANKBID_WEBHOOK_SECRET) {
    // Process request
} else throw new Error('Invalid signature');

Was this page helpful?