Webhooks

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://webhooks.bearer.sh/...) . 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 catched by Bearer and sent to your app (with a retry logic in case your application doesn't reply successfully).

Only webhook with a JSON payloads are supported. Indeed, Bearer parses the request from the API provider in a JSON format and forward it by enforcing the header Content-Type: application/json

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.

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((resolve, reject) => {
// 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

Responses

Bearer will forward the response from your application back to the API Provider.