1. Home
  2. v2
Webhooks

Webhooks

Webhooks are customizable HTTP callbacks that are defined by the user and triggered by specific events. When the designated trigger event takes place, the RCS API client detects the event, gathers the relevant data, and promptly sends a notification (in the form of an HTTP request) to the Webhook URL specified in the application settings. This notification serves to update the status of sent messages or inform you when a new message is received, click here to create webhook.

It is crucial to ensure that your Webhook returns an HTTPS 2xx OK response when receiving notifications. If the response is not received or does not meet the required criteria, the RCS API client interprets it as a failed notification and attempts to resend it after a certain delay.

If the webhook fails to send a response with a 2xx status code, or if the remote app does not respond within 3 seconds, the package considers the call as failed. In such cases, we will make two additional attempts to send the webhook call.

To avoid overwhelming the remote app, we introduce a delay between each retry attempt. By default, we wait 10 seconds between the first and second attempt, 100 seconds between the third and fourth attempt, 1000 seconds between the fourth and fifth attempt, and so on. The maximum wait time is set at 100,000 seconds, equivalent to approximately 27 hours. This ensures that we do not excessively burden the remote app while allowing for reasonable retry intervals.

If you wish to have your callbacks signed and have made the proper configuration for this, the callbacks will have the following signature-related headers.

Name Description
Signature The signature generated by system with webhook id as secret 
{
  "event": "rcs:message:status",
  "payload": {
    "id": "a418d672-9781-4d97-b517-a56f7d95ad8a",
    "channel": "rcs",
    "from": "700969ca-0cb2-11ec-a2cxxxx",
    "to": "9190199xxxxx",
    "status": "sent|delivered|read|failed|deleted",
    "delivered_at": "2021-06-18T14:48:06.886358Z",
    "read_at": "2021-06-18T14:48:06.886358Z",
    "processed_at": "2021-06-18T14:48:06.886358Z",
    "timestamp": "2021-06-18T14:48:06.886358Z",
    "foreign_id": "your-business-identifier"
  }
}

{
  "event": "rcs:message:in",
  "payload": {
    "id": "our-message-id",
    "channels": [
      {
        "name": "rcs",
        "to": "919019120xxx"
      }
    ],
    "recipient": {
      "from": "91XXXXXX",
      "user": {
        "id": "unique-id",
        "identifier_id": "unique-identifier-id",
        "subscriber_id": "unique-subscriber-id",
        "identity": "unique-user-identity",
        "username": "username",
        "first_name": "user first name",
        "middle_name": "user middle name",
        "last_name": "user last name",
        "email": "user email",
        "phone": "user phone number",
        "attributes": "user attributes",
        "user_info": {
          "picture": "null",
          "gender": "user-gender",
          "title": "null"
        }
      }
    },
    "message": {
      "type": "text",
      "payload": {
        "text": "This is a simple text message from whatsapp channel"
      }
    }
  }
}

{
  "event": "rcs:message:in",
  "payload": {
    "id": "our-message-id",
    "channels": [
      {
        "name": "rcs",
        "to": "919019120xxx"
      }
    ],
    "recipient": {
      "from": "91XXXXXX",
      "user": {
        "id": "unique-id",
        "identifier_id": "unique-identifier-id",
        "subscriber_id": "unique-subscriber-id",
        "identity": "unique-user-identity",
        "username": "username",
        "first_name": "user first name",
        "middle_name": "user middle name",
        "last_name": "user last name",
        "email": "user email",
        "phone": "user phone number",
        "attributes": "user attributes",
        "user_info": {
          "picture": "null",
          "gender": "user-gender",
          "title": "null"
        }
      }
    },
    "message": {
      "type": "image",
      "payload": {
        "url": "https://domin-name.com/your_image_path.png",
        "caption": "some caption for image",
        "filename": ""
      }
    },
    "id": "94e6ce87-1429-4e98-9715-2ec461401fd2",
    "timestamp": "2024-07-04T05:50:08.299202Z"
  }
}

For users seeking enhanced customization, compose webhook will help to receive the customized webhook payload to precisely match your preferences and requirements.

  • Navigate to the Webhooks section and click on the Compose Webhook.
  • Give the identification name.
  • To set up the Compose Webhook, you need to provide a callback URL. This URL is where the composed payload will be sent.
  • In the url you can pass the replaced variables.
  https://www.domain.com/ack/receive?id={{payload.id}}&mobile={{payload.mobile}}&status={{payload.status}}  

  https://www.domain.com/ack/receive?message_id={{payload.id}}&mobile_number={{payload.mobile}}&message_status={{payload.status}}
  • HTTP Method: Specify the HTTP method for the webhook request, such as GET, POST or PUT.
  • Headers: Define custom headers if needed, like Authorization headers or custom headers.
  • Body Format: Choose between JSON or FormData for the payload.
  • Upon creation, you will receive an id for the newly created Webhook.
  • To request delivery reports, include the webhook_id parameter and its corresponding value in your API Request. Once the request is made, you will receive the delivery report as you configured.
  • here keys you can give any name but value should be availebe in the below replaced variables Ex: {{payload.mobile}}.
  curl -X POST \
  https://www.domain.com/ack/receive?id={{payload.id}} \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer %token%", \
  -d '{
      "id": "{{payload.id}}",
      "mobile": "{{payload.mobile}}",
      "message_status": "{{payload.status}}",
      "read_at": "{{payload.read_at}}"
    }'

Replaced Parameters can be used while creating or composing a webhook

Name Description
id Message Id generated by us
from Whtsapp business number
to Mobile number with country code
status sent|delivered|read|failed|deleted
delivered_at Delivered to handset time
read_at user message read time
processed_at Processed time
submit_time Sent to operator time
foreign_id your-business-identifier
Table of Contents