Configure

Webhooks can be configured at the client level. You are required to enter the following:

• Webhook URL – Must start with https://.
• Webhook Secret – A maximum of 64 characters secret to help validate webhooks.

Once completed – Webhooks will be emitted for the following events:

• Enrollment Status
• Transaction Status

Structure

All webhooks follow the same exact payload below.

{
    "tag": "string",
    "created_at": "ISO8601",
    "data": {},
    "uuid": "string"
}

• tag – colon delimited key, like transaction:status.
• created_at – ISO 8601 date format.
• data – The payload itself.
• uuid – A UUID v4 to detect duplicate events.

Security

Webhooks include a X-Signature HTTP header which reflects a secure hmac of the payload included. This hmac is produced from the payload and the webhook secret.

So while the code syntax may be different. You could try the following PHP snippet to verify a webhook.

$body = file_get_contents('php://input');
$secret = 'webhook-secret-value';
$webhookSignature = hash_hmac('sha256', $body, $secret);

The snippet above has remade the signature that was provided in X-Signature. All that remains is a simple time safe comparison (hash_equals). If those match – the webhook can be trusted.

Retry behavior

The webhooks require an HTTP status code in the 200 region in order to be marked as success. If not, it will automatically be retried 3 times, waiting 3 seconds in between retries.

Webhook Types

Enrollment Status

{
    "tag": "enrollment:status",
    "created_at": "2020-07-09T17:07:49Z",
    "data": {
        "id": "enrollment_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
        "status": "created"
    },
    "uuid": "d8661b68-ca10-4cd0-a464-9fa3de5de336"
}

This data payloads returns two keys and emits any time an enrollment has a status change.

• id – Permanent unique identifier of the enrollment intent.
• status – The current status of the enrollment intent.

Transaction Status

{
    "tag": "transaction:status",
    "created_at": "2020-07-09T17:07:49Z",
    "data": {
        "id": "transaction_intent_Aa1ABb2BCc3CDd4DEe5EFf6FGg7GHh8H",
        "status": "pending_service_fee_acceptance"
    },
    "uuid": "5085db09-80de-4c3a-8a7b-619bfc2cddaf"
}

This data payloads returns two keys and emits any time a transaction has a status change.

• id – Permanent unique identifier of the transaction intent.
• status – The current status of the transaction intent.