Webhook Support

When APIs provide webhook, Bearer will act as a concentrator and forwarder. Our server-side clients help you receive webhooks in a standardized and secure way, automatically dealing with:

  • Encrypting/Decrypting

  • Applicative acknowledgement

  • Retry Logic (aka circuit breakers)

Configuring Webhook URLs

Webhook configuration requires two steps.

First, under the Settings tab of each integration, you have to configure the URL where you wish to receive the webhooks (e.g. https://myapp.com/bearer/webhooks):

A forward URL is provided in return (https://wehooks...) . Use this URL to setup the webhook on the API Provider developer website.

Receiving Webhooks

Once a webhook is setup, any webhooks triggered from the API Provider will be sent to your app.

Validating requests

To help receive and validate the signature of a webhook within your application, the integration clients provide helper methods.

Here is an example:

Express.js
Rails
import bearerWebhooks from '@bearer/express'
const EncryptionKey = process.env.BEARER_ENCRYPTION_KEY
const webhookHandlers = {
['INTEGRATION-UUID']: req =>
new Promise(() => {
// you logic goes here
if (something) resolve()
else {
reject()
}
})
}
app.use('/bearer/webhooks', bearerWebhooks(webhookHandlers, { token: EncryptionKey }))
# in config/initializers/bearer.rb
Bearer::Configuration.setup do |config|
config.secret = BEARER_ENCRYPTION_KEY
end
# in config/routes.rb
Rails.application.routes.draw do
mount BearerRails::Webhooks.new, at: '/bearer/webhooks'
end
# in app/webhooks/my_handler.rb
class MyHandler
include BearerRails::Webhook
integration_handler "INTEGRATION_UUID"
def call
consume_webhook_service(body)
end
end

Retry logic

Bearer will attempt to call your application up to four times until a 2XX or 3XX response is returned. There will be a random delay between each attempt.

Responses

Bearer will forward the response from your application back to the API Provider. Currently, only JSON payloads are supported.