Callback Best Practices

Callback Best Practices

A callback (also known as a webhook) has become an industry standard for sharing platform information needing to be relayed back to an application, yet the specific timing upon when this information becomes available is unknown.  For example, if a person needed to talk to a physician they might call them on the phone.  Instead of holding on the phone (indefinitely) until the physician is free, the person would leave a message providing their callback number, enabling the physician to return their call when available.  This is similar to how (and why) a callback works.  An application registers a URL endpoint so the platform may return information when processing has completed (versus keeping an open connection and waiting for an indefinite amount of time).

Verizon uses callbacks to help optimize communication between its platform and your application.  While some API’s are asynchronous, which require the use of callbacks (such as activating up to 10,000 devices at once), other API’s are able to provide a synchronous (near instant) response.  Synchronous responses such as /devices/actions/list will return the status of devices on an account when the API is called since the response only takes seconds to process.  Asynchronous responses such as /devices/actions/activate will return a tracking identifier (RequestID) synchronously and then later return the full response via your registered callback URL (webhook) service since processing time is greater than several seconds (and may vary based on server load and / or how many devices were included with the request).  NOTE: The callback data will include the RequestID for tracking purposes. 

The below image shows the ladder logic of both synchronous and asynchronous (callback) returns:

 

In addition to the above, one other great use of callbacks is to notify you of changes to the platform that were outside of an API event.  For example, if you register for the ExternalProvisioningChanges callback, this prompts traffic from Verizon to your URL endpoint notifying you when changes to a device are processed outside of the API communication method (such as when someone calls in to manually deactivate a line of service).  Another example might be if a support staff logs into the ThingSpace web portal and changes a custom field manually, your application (or platform) would likely be out of sync with ThingSpace unless it were to receive the ExternalProvisioningChanges callback informing you to update the changes to the line.  This helps keep your platform up to date with the latest information.

A number of other callback services are available.  Further information is available at this link.

It is recommended at a minimum to register for CarrierService and ExternalProvisioningChanges.

For a more thorough explanation of what to check for during an activation, see Activation Best Practices.

Setting up a Callback Service

NOTE: If you are unable to utilize callbacks at this time, it is recommended to login to the ThingSpace web portal and review the Logs for any processing information.

Prior to launching a full production callback you may find it easier to set up a temporary callback endpoint with a service such as https://webhookrelay.com/, or https://webhook.site/.  Talk to your Verizon Developer Relations Engineer for further options Please be aware that Verizon neither endorses nor recommends these sites. They are only provided as an example.  Be sure to deregister your test callback URL before registering a new production callback endpoint.
At this time you may only register one callback endpoint per service per account.  If you need to send callbacks to multiple endpoints you will need to store and forward them or use a service such as https://webhookrelay.com/ (Neither endorsed or recommended by Verizon. Just an example).

 

Setting up a callback service (see link for video) will require your endpoint to accept unsolicited inbound traffic. You must first tell Verizon the URL of your callback web service so that Verizon knows where to send the data.  NOTE: There may be firewalls on your network that restrict inbound traffic.

Below is a diagram for reference along with the IP addressing from Verizon that you will need to permit; please see this link for the latest listing of IP addresses.

  • Work with your IT Dept. to determine the path through your network to your  web service

  • Be sure your web server’s firewall allows incoming traffic from Verizon on the port you register;  when you register a callback, we only allow the following ports: 

    • 80

    • 443

    • 9001-9006

    • 50551-50559

    • 28200-28220

  • Register the correct URL or IP address and port

  • Be sure the URL or IP address is the outside publicly accessible IP address

  • There are multiple services you can register for

  • Be sure you are registering the correct service for the API set

  • You can register one service per account

  • For each account you have you can register for one, many or all of the Verizon API callback services available depending on what information you are looking to receive

  • The username/password section is not a login mechanism (this information is sent with the callback to help with your processing).  It is sent in clear text, do not put information in that you do want others to see

  • Be sure your service knows where to look and what to do with the username and password when it receives it

  • Consider first testing without the username/password

  • If you use https you must have a valid certificate registered with a legitimate certificate authority

  • A self-signed certificate will not work

Testing your callback service

  • RegisterCarrierService callback for your account. This is the same callback used  for activations

  • To generate API calls that are fast and require minimal processing by Verizon use CarrierService/ChangeDeviceCustomFields

  • Change a custom field you are not actively using

  • Consider using a variable such as time and date as the field you are changing so it is easily recognizable as a change

  • Before trying https, or if https fails, try http first as it removes one complexity

  • Remember to unregister the https URL and register the http URL or visa versa  depending on your testing

 

SFAQ:  Semi-Frequently Asked Questions

Q: The callbacks don’t include the account number on which the callback was triggered; is there any easy way to know which account the callback is coming from if I work with multiple accounts?

Yes!  When you register a callback, there is an option for a username and password, which is used for your callback endpoint application to verify against.  Most customers do not use these fields as the best approach is to use HTTPS (along with a certificate) as an endpoint which has overall better security.  Thus, you can use the username field when you register a new callback for anything you'd like.  So, you could enter the account number inside of the username field so that each time you receive a callback, the account number would be included within the username field for that specific callback type on that account.  You could also use the password field for anything else you’d like included with the callback.  Keep in mind that username and password fields are clear text if you are not using https.