Skip to main content

​
Setting up webhooks

To receive webhooks, specify a webhook URL in the pairing request. Once set up, Payment Service will send webhook events to that URL whenever relevant actions take place.

​
Webhook security and signing

Each webhook request is signed using an HMAC SHA256 signature, based on the exact JSON payload sent in the body. This signature is included in the Signature HTTP header of the request. The secret key used to compute the signature is returned in the pairing response, which is part of the Terminal Pairing flow. You can verify webhook authenticity by computing the HMAC signature and comparing it to the Signature header included in the webhook request.

​
Example: Verifying a webhook signature

def verify_hmac_signature(payload: str, signature: str, secret_key: str) -> bool:
    """
    Verify HMAC signature from webhook header.

    Args:
      payload: JSON string with sorted keys (must match how signature was generated)
      signature: The signature hexdigest from Signature header
      secret_key: The webhook secret key for HMAC verification
    """
    computed_signature = hmac.new(secret_key.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed_signature, signature)
  • 200 OK - Accepted and processed
  • 400 Bad Request - Invalid payload or known exception (triggers retries)
  • 403 Forbidden - Signature verification failed
  • 500 Internal Serviver error - Temporary server issue (triggers retries)

​
Retry mechanism

We perform 5 retries with exponential backoff (5s, 10s, 20s, 40s and 80s). After all retries are used, the infomation can be retrieved with polling endpoints.