Receiving message webhooks with the Volt GraphQL API
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:
Have your Volt GraphQL API access token readily available. If you are unsure of where to locate your API token, contact api@textvolt.com.
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:
Set the
Authorization
header to the valueBearer <token>
, replacing<token>
with the API access token belonging to your organization.Construct a GraphQL query using the
registerWebhook
mutation:mutation registerWebhook ($url: String!) { registerWebhook (url: $url) { id url createdAt lastUpdatedAt } }
Construct a JSON object containing the GraphQL variables for the query created in the previous step:
{ "url": "https://example.com/webhooks" }
Send a
POST
request tohttps://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 receivePOST
requests containing webhook notification event data related to your SMS messages.
Trouble Shooting
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.