Skip to main content

Setting up Webhooks

Use Webhooks to receive notifications about events that happen in your Rinkel account. For example, you can receive a notification when a call is made to one of your Rinkel numbers, or when a call is answered.

Rinkel will send a HTTP POST request to the URL you specify in the Webhook configuration. The request will contain a JSON payload with information about the event that happened. This url:

  • must be HTTPS
  • must be reachable from the public internet
  • must be able to handle HTTP POST requests
  • must respond with a HTTP 200 OK status code within 2 seconds
note

Webhooks are only available in the Expert plan.

Setup in the My Rinkel interface​

To start using Webhooks, follow these steps:

  1. Log into My Rinkel and go to the Webphone page
  2. Click on the Settings icon in the top bar and go to Integrations
  3. Click on any of the Events: (incoming call, outgoing call, call start, call end, call insights)
  4. Enter the URL of the endpoint you want to receive the Webhook events on and click the Test button
note

We will send a test Webhook event to the URL you specified. If the test was successful, you will see a green checkmark. If the test failed, you will see a red cross. In that case, please check the logs of your endpoint to see what went wrong.

  1. Select the desired Content-Type for the Webhook event: application/json or application/x-www-form-urlencoded.

  2. Enter a description for your Webhook (optional)

  3. Click the Save button to save your Webhook configuration

Setup using the Rinkel API​

You can use the Rinkel REST API to programmatically subscribe/unsubscribe from webhook events. Check the API Reference for more information.

note

The Rinkel REST API is now in beta. If you're keen to be part of this beta phase and explore the integration possibilities, request your API key from https://www.rinkel.com/en-nl/integrations/.

Webhook events​

Incoming call​

This Webhook event is triggered when a call is made to one of your Rinkel numbers. It sends a POST request to the URL you specify in the Webhook configuration with the following JSON payload:

{
  "id": "1c8b83a7c690084224ec3984515bc1a2",
  "datetime": "2023-06-14T13:56:24.969Z",
  "to": "+31850609000",
  "from": "+31850609001"
}
  • id: The unique ID of the call. This ID will be the same for all Webhook events related to this call.
  • datetime: The date and time when the call was made.
  • to: The Rinkel number that was called in E.164 format.
  • from: The number that made the call in E.164 format, or anonymous if the caller withheld their number.

Outgoing call​

This Webhook event is triggered when a call is made from one of your Rinkel numbers. It sends a POST request to the URL you specify in the Webhook configuration with the following JSON payload:

{
  "id": "1c8b83a7c690084224ec3984515bc1a2",
  "datetime": "2023-06-14T13:56:24.969Z",
  "to": "+31850609000",
  "from": "+31850609001"
}
  • id: The unique ID of the call. This ID will be the same for all Webhook events related to this call.
  • datetime: The date and time when the call was made.
  • to: The number that was called in E.164 format.
  • from: The Rinkel number that made the call in E.164 format.

Call start​

This Webhook event is triggered when an incoming or outgoing call is answered. It sends a POST request to the URL you specify in the Webhook configuration with the following JSON payload:

{
  "id": "1c8b83a7c690084224ec3984515bc1a2",
  "datetime": "2023-06-14T13:56:24.969Z",
  "answeredBy": "[email protected]",
  "choice": "1"
}
  • id: The unique ID of the call. This ID will be the same for all Webhook events related to this call.
  • datetime: The date and time when the call was answered.
  • answeredBy: The e-mail address of the user that answered the call.
  • choice: The choice that was made by the user in the voice menu, if applicable. This will be null if the Rinkel number has no voice menu.

Call end​

This Webhook event is triggered when an incoming or outgoing call is hung up. It sends a POST request to the URL you specify in the Webhook configuration with the following JSON payload:

{
  "id": "1c8b83a7c690084224ec3984515bc1a2",
  "datetime": "2023-06-14T13:56:24.969Z",
  "cause": "ANSWERED"
}
  • id: The unique ID of the call. This ID will be the same for all Webhook events related to this call.
  • datetime: The date and time when the call was hung up.
  • cause: The reason why the call was hung up. This will be one of the following values:
    • UNANSWERED - The call was not answered.
    • ANSWERED - The call was answered.
    • BLACKLISTED - The call was blocked by the blacklist.
    • VOICEMAIL - The call was sent to voicemail.
    • CALLCENTER - The call was sent to our answering service.
    • OUTSIDE_OPERATION_TIMES - The call was made out of your operation times. Only applicable if you have operation times configured.

Call insights​

This Webhook event is triggered when AI Insights have been generated for the call. It sends a POST request to the URL you specify in the Webhook configuration with the following JSON payload:

{
  "id": "1c8b83a7c690084224ec3984515bc1a2",
  "sentiment": "POSITIVE",
  "topics": ["sales", "support"],
  "summary": "This is a summary of the call."
}
  • id: The unique ID of the call. This ID will be the same for all Webhook events related to this call.
  • sentiment: The sentiment of the call, either POSITIVE, NEUTRAL or NEGATIVE.
  • topics: The topics that were discussed during the call. This will be an array of strings with a maximum of 4 values. Could be a single word or a small phrase.
  • summary: The summary of the call.

Retry mechanism​

If the Webhook endpoint does not respond with a 200 HTTP status code, the Webhook will be retried once every hour for 24 hours. If the Webhook is still not successful after 24 hours, the Webhook will be disabled and you will receive an e-mail notification.