The Orum Webhooks feature allows developers to configure webhook endpoints to receive real-time notifications when specific events occur within the Orum platform. This enables seamless integration with external systems for automation, logging, or data synchronization.

• Simply put: After a call is completed in Orum, we can send the details of that call to any system that supports Webhooks.

• Note: Webhooks are an add-on feature to your Orum subscription. They are designed to be implemented and supported by your company's internal technical resources. We recommend confirming that these resources are available prior to purchase. Please contact your Orum account representative for pricing information.

What Call Data can be sent? AKA The Webhook Payload

Orum will include the following call properties in the response payload. These are the "fields" of data we send with every call completed.
datetime
call duration
disposition
list name
notes
objections
recording URL
user email address
recording type
inbound or outbound call
call transcript
prospect name
prospect phone number

How to Add a Webhook

1. Navigate to Webhook Settings:

   1. Go to Settings → System → Webhooks.

   2. Select the organization from the dropdown menu if applicable.

2. Click “Add Webhook”

   1. Press the + ADD WEBHOOK button.

3. Configure Webhook Details:

   1. Event Type: Select the event that will trigger the webhook (e.g., “Call Disposition Added”).

   2. Webhook URL: Enter the URL where the event data will be sent.

   3. Webhook Signing Key (Optional): Provide a key to verify webhook payload authenticity.

   4. Description (Optional): Add a short description for reference.

4. Test the Webhook (Optional):

   1. Click TEST WEBHOOK to send a test payload to the specified URL.

   2. Ensure your endpoint is correctly set up to receive and process the data.

5. Save the Webhook:

   1. Click the SAVE button to finalize the setup.

Receiving Webhook Requests

When your webhook endpoint receives requests, the payload will have the following format:

{
  "event": "call-disposition-added",
  "payload": ...,
  "test": true
}

• event: A string identifying the event that triggered the webhook (e.g., "call-disposition-added").

• payload: The actual data related to the event. This will vary based on the event type.

• test: This property is only present for test requests (when the TEST WEBHOOK button is clicked in the settings). For actual requests, this property will not be included.

Important: Make sure your endpoint checks for the test flag before processing the data to avoid consuming test data.

Verifying the Signature

Each webhook request contains a signature in the x-webhook-signature header. This signature is created to ensure the request is authentic and that the data has not been tampered with. The signature is generated using HMAC with the SHA256 algorithm and then encoded in base64. The format of the signature is:

{timestamp}.{stringified_body}

The x-webhook-signature header will look like this:

t={timestamp},s={encoded-signature}

Steps to Verify the Signature:

1. Extract the Signature Components:

   1. Split the x-webhook-signature value by the comma (,) to extract the timestamp and signature.

2. Construct the Payload Signature:

   1. Concatenate the following:

      1. timestamp (as a string)

      2. "." (a period)

      3. The stringified JSON payload.

3. Generate the Signature:

   1. Using the webhook’s signing key (configured in Orum's settings), generate the signature using HMAC and the SHA256 algorithm.

4. Compare the Signatures:

   1. Compare the generated signature with the one sent in the x-webhook-signature header. They should match exactly.

5. Check the Timestamp:

   1. If the timestamp is more than five minutes old compared to the current time, you may choose to reject the payload for additional security.

Example of Signature Verification in Node.js:

onst crypto = require('crypto');
// Extract the timestamp and signature from the x-webhook-signature header
const timestamp = signatureHeader.split(",")[0].substring(2);
const signature = signatureHeader.split(",")[1].substring(2);
// Construct the value to be signed
const value = ${timestamp}.${requestBody};
// Generate the signature using HMAC and SHA256
const recreatedSig = crypto.createHmac("sha256", webhookSigningKey).update(value).digest("base64");
// Verify the signature using timingSafeEqual
const isValid = crypto.timingSafeEqual(Buffer.from(signature, 'utf8'), Buffer.from(recreatedSig, 'utf8'));
// Check if the timestamp is within a valid range (5 minutes)
const date = new Date(parseInt(timestamp));
const isWithinFiveMinutes = (Date.now() - date) < 60000;
if (isValid && isWithinFiveMinutes) {
  // Process the request
} else {
  // Reject the request
  console.error("Invalid signature or expired timestamp.");
}

How to Remove a Webhook

1. Navigate to the Webhook Settings:

   1. Go to Settings → System → Webhooks.

2. Locate the Webhook to Remove:

   1. Find the webhook from the list (if any are configured).

3. Delete the Webhook:

   1. Click the delete or remove option (button not shown in screenshots; confirm if available).

   2. Confirm the action if prompted.

How to Test a Webhook

1. During Webhook Creation:

   1. Click the TEST WEBHOOK button before saving.

   2. This sends a test request to the configured Webhook URL.

2. Verifying the Test Response:

   1. Ensure your server receives the request and processes it correctly.

   2. Test requests include "test": true in the request body to help endpoints identify those dummy requests.

   3. Check the logs in your endpoint to confirm the structure of the received payload.

How to View Webhook Logs

1. Navigate to Webhook Logs:

   1. Go to Settings → System → Webhooks.

   2. Click the VIEW WEBHOOK LOGS button.

2. Filter Logs:

   1. Select an Event Type from the dropdown.

   2. Choose a Date Range to narrow down results.

3. Review Log Details:

   1. The log table will display:

      1. ID – Unique identifier for the webhook event.

      2. URL – The destination where the webhook was sent.

      3. Status – Whether the webhook was successfully delivered or failed.

      4. Inserted At – Timestamp of when the event was triggered.

4. Troubleshooting Failed Webhooks:

   1. If no records are shown, verify that events are being triggered.

   2. If webhooks fail, ensure the Webhook URL is reachable and accepts POST requests.

Webhook Delivery and Retry Mechanism

• Orum expects the receiving endpoint to return a 2xx HTTP status code upon successful webhook processing.

• If a webhook fails (i.e., a non-2xx response is returned or the request times out), Orum implements an exponential backoff retry strategy.

• The retry intervals start small and increase exponentially to avoid overwhelming the receiving system.

• Webhooks have built-in retries for 3xx, 4xx, and 5xx responses from your endpoint. Make sure to send a 2xx (i.e. 200) response from your endpoint once you've received the webhook request before operating on the data to avoid a timeout, which will result in the webhook being retried. We will retry delivery up to 8 times over a 30-minute window, utilizing an exponential back-off strategy with jitter.

• If all retry attempts fail, the webhook event will be logged as failed in the Webhook Logs.

Additional Notes

• Ensure your webhook endpoint can handle incoming JSON payloads.

• Use the Webhook Signing Key to validate incoming requests.

• Configure your endpoint to acknowledge webhook requests quickly to prevent unnecessary retries. Requests time out in ~15 seconds.

• Please note that WebHooks data is provided via the chosen configuration moving forward only. There is not an option for historical records at this time.