Webhooks

Webhooks allow you to build or set up applications which subscribe to certain events in RamBase. When one of those events is triggered, we will send a HTTP POST payload to the webhook's configured URL.

1. Setting up new webhooks

Webhooks are created and maintained in the WEBHOOK application inside the RamBase client (www.rambase.net). You can change the webhooks through the API or UI anytime. The following can be specified:

• Name of the webhook
• The server endpoint that will receive the webhook payload
• Which RamBase event to listen to
• Which companies to listen for the event in, and which users to ignore
• Which format or content type to use. JSON or XML
• Payload content. For some RamBase events you can specify different payloads to receive with the request. This is either the event parameters or details from specific API resources.
• Optional secret token and hash function for validating the payload. Read more below

2. Example events

When configuring a webhook, you can choose which event you would like to receive payloads for. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. Note that the RamBase events only covers parts of the RamBase product. Do not hesitate to contact us if you are missing any RamBase events, as we are continuously working to expose new functionality.

In the example below a webhook was configured to be sent by JSON and triggered by the ContactUpdated event:

{
    "SystemID": "HATTELAND",
    "RamBaseEventId": 821750,
    "EventType": "ContactUpdated",
    "Database": "TEM-NO",
    "RegisterTime": "2020-07-17T10:58:56Z",
    "RegisterPid": 8201,
    "Parameters": [
        {
            "ParameterName": "ContactId",
            "ParameterValue": "101816"
        }
    ]
}

3. Securing your webhooks

Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. If you for security reasons want to limit request to your endpoint to only those from RamBase, it is possible to set up a secret token and validate the incoming payloads.

When you configure your webhooks, you need to specify a secret token and a hash algorithm to use. When your secret token is set, RamBase uses it to create a hash signature with each payload. This hash signature is passed along with each request in the headers as X-RamBase-Signature. When you receive a payload, compute a hash of the payload using your secret token, and ensure that the hash from RamBase matches. RamBase uses a Hash-based message authentication code (HMAC) hexdigest to compute the hash. Note that the hash signature is base64 encoded.