Webhooks (UNDER HEAVY CONSTRUCTION)

A webhook allows you to connect a platform you manage (either an API you create yourself, or a third party service) to a stream of future events.

Setting up a webhook on autoZnetwork enables you to receive information (referred to as events) from autoZnetwork, as they happen. This can help you avoid polling the API or manually checking the autoZnetwork web application for desired information.

Quickstart

Webhooks are set up on a per-organization basis, either within the autoZnetwork application or via API.

To configure webhooks via API see our documentation for autoZnetwork Webhooks API

To configure webhooks within the autoZnetwork application:

Visit your organization settings on autoZnetwork

  • In the sidebar of your Organization Settings, click on Webhooks
  • Click Add Webhook
  • Fill out the webhook form (the table below describes the fields and their intent)
  • Provided your receiving API or third party service is set up, click Test Webhook Event to dispatch a test event. Note that the test webhook event has an abbreviated payload for ease of testing. See full examples of test events below.
FieldRequired?Intent
URLYThe URL the webhook will make POST requests to
Certificate ValidationYEnsure the receiving host has a valid SSL certificate before sending an event*
Secret TokenNUsed by your API/platform to validate incoming data is from autoZnetwork
EventYYou must select at least one event that will trigger a webhook

*Only leave this unchecked for testing purposes.

Communication protocol with webhooks

A webhook is sent whenever an event occurs on the autoZnetwork platform.

A webhook is sent using an HTTP POST to the URL that was registered when the webhook was created, with a body encoded using JSON.

autoZnetwork expects the server that responds to a webhook will return a 2xx response code. If a non-2xx response is received, autoZnetwork will retry at a later time. If autoZnetwork does not receive a response to the webhook within a short period of time, autoZnetwork will assume that delivery has failed, and will retry at a later time. The timeout period is currently 5 seconds.

Webhook requests may be duplicated. To deduplicate (prevent requests from being duplicated for a specific event), use the id property in the webhook payload for identification.

If you have feedback about timeouts and retries, please get get in touch with our team.

Webhook headers

A number of HTTP headers are set on webhooks, as detailed in the table below.

Header NameValue
content-typeapplication/json
user-agentAutozNetwork-Webhook/1.0
AutozNetwork-SignatureWhen present, this signature can be used to verify that the sender of the webhook has access to the secret token.

Validate Webhooks

You should validate incoming webhooks to verify that they are coming from autoZnetwork. To support this, when creating a webhook, you can optionally provide a secret token. Each outgoing HTTP request to your service will contain a AutozNetwork-Signature header.

POST /uri HTTP/1.1
Host: your-webhook-host
AutozNetwork-Signature: 4fcc06915b43d8a49aff193441e9e18654e6a27c2c428b02e8fcc41ccc2299f9

autoZnetwork generates signatures using a hash-based message authentication code (HMAC) with SHA-256.

Here are some example signatures for given request bodies:

BodySecret KeySignature
hello worldsecret734cc62f32841568f45715aeb9f4d7891324e6d948e4c6c60c0621cdac48623a

The following is an example of how you might validate signatures:

PHP
Example here
Python
import hmac

def verify_signature(secret, headers, body):
  # get the signature from the `AutozNetwork-Signature` header
  signature_from_header = headers['AutozNetwork-Signature']

  # Run HMAC-SHA256 on the request body using the configured signing secret
  valid_signature = hmac.new(bytes(secret, 'utf-8'), bytes(body, 'utf-8'), 'sha256').hexdigest()

  # use constant time string comparison to prevent timing attacks
  return hmac.compare_digest(valid_signature, signature_from_header)

# the following will return `True`
verify_signature(
  'secret',
  {
      'AutozNetwork-Signature': '773ba44693c7553d6ee20f61ea5d2757a9a4f4a44d2841ae4e95b52e4cd62db4'
  },
  'foo',
)

# the following will return `False`
verify_signature(
  'secret',
  {
      'AutozNetwork-Signature': 'not-a-valid-signature'
  },
  'foo',
)
Table of Contents