Receiving message webhooks with the Volt GraphQL API

Created by Cody Crow,
Last updated: Oct 25, 2024
5 min read

You can choose to receive notification events about your SMS messaging by registering webhooks. This is a step-by-step guide to registering a webhook to receive notification events when a message is sent, finalized, or received.

Update

You can now register webhooks through our web portal. In Volt Messaging, navigate to the Webhooks tab in your Account Settings to register new webhooks and update existing connections.


Note: during registration, an automated test request is sent to your webhook URL. Your server must return a successful response (2XX status code) to complete registration.

 Instructions

First, ensure that you have access to the data necessary for utilizing the Volt GraphQL API:

  1. Have your Volt GraphQL API access token readily available. If you are unsure of where to locate your API token, contact api@textvolt.com.

  2. In order to receive webhooks, you will need a publicly accessible HTTP server capable of listening for POST requests. We recommend implementing HTTPS for securely receiving webhook events.

If you register a webhook URL, notification events will be sent to that URL for any phone number belonging to your organization. Any routing based on the sending or receiving phone number, or any other information relating to a message, should be handled as needed within the server that handles the webhook events.

To register a URL for receiving webhook notification events, use the Volt GraphQL API:

  1. Set the Authorization header to the value Bearer <token>, replacing <token> with the API access token belonging to your organization.

  2. Construct a GraphQL query using the registerWebhook mutation:

    mutation registerWebhook ($url: String!) { registerWebhook (url: $url) { id url createdAt lastUpdatedAt } }

     

  3. Construct a JSON object containing the GraphQL variables for the query created in the previous step:

    { "url": "https://example.com/webhooks" }

     

  4. Send a POST request to https://api.respondflow.com/graphql with the GraphQL query and variables in the request body. We recommend using a GraphQL client library in the language of your choice to construct and send GraphQL API requests.

    For example, to send the above GraphQL request using curl:

    curl --location --request POST 'https://api.respondflow.com/graphql' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{"query":"mutation registerWebhook ($url: String!) {\n registerWebhook (url: $url) {\n id\n url\n createdAt\n lastUpdatedAt\n }\n}","variables":{"url":"https://example.com/webhooks"}}'


    Once a webhook is registered, you should receive POST requests containing webhook notification event data related to your SMS messages.

Troubleshooting

Our server expects to receive a status code 200 from a successful POST request to the registered url, otherwise you will receive this error

Error from GraphQL API: webhook failed to respond successfully

 

 Example webhook payloads

When a message is received

When a message is sent to carrier

When a message is finalized

When a message is delivered

When a message fails to deliver

Validating webhooks

Each Volt webhook notification event that we send you will include a cryptographic signature in the X-Respond-Flow-Signature header. The signature allows you to validate that webhooks were not sent by a third-party.

Our RSA public key is available at https://callbacks.respondflow.com/id_rsa.pub, which can be used to validate the signature sent with each request using a standard cryptographic library in your language of choice.

 Related articles