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.
Webhooks are only avialable for the Business and Enterprise plans. You can change plans in your dashboard settings at any time.
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');
Do not expose your webhook signing secret to the public. In particular, make sure your signing secret is not included in your git history and do not hardcode it in your application code. Depending on how you deploy your application, envirionment variables may be a viable option for storing your signing secret.