Handling Webhook Events

4min

If you've gone through our Webhooks Quickstart, you should be able to receive events. Here, we'll talk about the events you'll receive and ways you might want to use them.
Event properties
Webhook events have a JSON body that always has as few top-level properties. Here's an example of the event that gets fired when a customer is created:
JSON
{
    "event_type": "customer.new",
    "idempotency_key": "733114a667199d09714d72d2bf55d69d",
    "data": {
        "vendor_name": "antler_db_inc",
        "customer_name": "test_customer"    
    }
}
{
    "event_type": "customer.new",
    "idempotency_key": "733114a667199d09714d72d2bf55d69d",
    "data": {
        "vendor_name": "antler_db_inc",
        "customer_name": "test_customer"    
    }
}
﻿
Note that there are three top-level properties:
event_type
idempotency_key
data
Webhook endpoints should be idempotent when possible
Since it is very hard to guarantee only-once delivery of webhook events, it is possible for your webhook endpoint to receive the same event more than once. Whenever possible, your webhook endpoint should be able to be called with the same event multiple times. We include an idempotency key to help uniquely identify an event, which can help identify the same event if it appears multiple times.
Signature
Octane signs every webhook event with an OCTANE-SIGNATURE header. This hash can be used to validate that the events came from Octane, and that they haven't somehow been tampered with in transit. For an added layer of security, you can validate the signature of messages received from Octane.
This signature is the hash of the entire payload. To generate this hash, we use a unique webhook secret, which we expose on the Credentials tab on the Settings page in our web portal.
Assuming you have your webhook secret, validating an event looks like this:
Python
Node.js
import hmac
import hashlib


def validate_event(secret: str, payload_body: str, signature: str) -> bool:
    """Validate the body of a webhook event
  
    Keyword arguments:
    secret         -- the webhook secret key for the account that owns the event
    payload_body   -- the body of the webhook event
    signature      -- the hash sent in the event's `Octane-Signature` header
  
    Returns true if the event is valid, false otherwise.
    """
  
    secret_bytes = secret.encode("utf-8")
    payload_bytes = payload_body.encode("utf-8")
    payload_hash = hmac.new(secret_bytes, payload_bytes, hashlib.sha256).hexdigest()
    return signature == payload_hash
import hmac
import hashlib


def validate_event(secret: str, payload_body: str, signature: str) -> bool:
    """Validate the body of a webhook event
  
    Keyword arguments:
    secret         -- the webhook secret key for the account that owns the event
    payload_body   -- the body of the webhook event
    signature      -- the hash sent in the event's `Octane-Signature` header
  
    Returns true if the event is valid, false otherwise.
    """
  
    secret_bytes = secret.encode("utf-8")
    payload_bytes = payload_body.encode("utf-8")
    payload_hash = hmac.new(secret_bytes, payload_bytes, hashlib.sha256).hexdigest()
    return signature == payload_hash
﻿
﻿

Webhooks

Supported Webhook Events

Docs powered by Archbee

TABLE OF CONTENTS

Event properties

Signature