Skip to main content

Send call start details

Please make sure you have an API up and running, similar to the endpoint shown below where 'your-custom-url' is your company domain. Onoff suggest to add an api-key as described in Authorization.

 POST https://<your-custom-url>/v1/onoff/call-start

The Call Start Webhook is sent the moment a call starts. It allows you to react in real time, for example by displaying caller information in your own systems. The full call details (duration, status, recording, etc.) are sent afterwards through the Send call log details webhook.

Request​

Body example​

{
  "id": "12345",
  "eventName": "CALL_START",
  "userId": "1712345678901-3f9a2b7c1d4e-0001",
  "onoffUserName": "John Doe",
  "onoffUserEmail": "john.doe@example.com",
  "onoffNumber": "1234567890",
  "externalNumber": "0987654321",
  "callDirection": "INBOUND",
  "callStarted": "2023-05-20 14:30:00 UTC"
}

Field explanation​

  • id String Unique id of the call start event
  • eventName String This is the type of the event sent. Possible values: CALL_START
  • userId String Unique id of the onoff user who is involved in the call
  • onoffUserName String Username of the onoff user who is involved in the call
  • onoffUserEmail String Email of the onoff user who is involved in the call
  • onoffNumber String Phone number of the person who has Onoff account
  • externalNumber String Phone number of the second party
  • callDirection String The direction of the call. Possible values: INBOUND, OUTBOUND
  • callStarted Date Date when the call started, in UTC

Response​

An empty Json or String is fine for us. What is important is that the HTTP Status in the response is 200 OK.

Body example​

{
}

Errors​

If after Onoff makes the request to your specific domain, we receive 4xx or 5xx HTTP Status in the response, we will retry 4 times more to deliver the event info. After the last attempt, we do not succeed in the delivery, onoff will discard the event meaning it will be lost.

Recommendations​

  • Idempotency: We look forward for you to implement a webhook in idempotent manner to avoid duplications in your side. A better explanation about the concept of idempotency here. Just note that each event that we send you has an unique UUID so that you can verify if it was processed before or not.

  • Timeouts: We expect your service to handle requests properly. Our service make request with the following timeouts

    • Connect timeout: 1000 ms
    • Read timeout: 10000 ms