Transition to UUID Webhook Codes

We are updating how webhook codes are generated within the PayAdvantage API. This change improves uniqueness guarantees and eliminates collision risks as our platform continues to scale.

What’s Changing?

Currently, webhook codes are 8-character uppercase hexadecimal strings (e.g., A1B2C3D8). We are transitioning these to a full UUID format — 36-character lowercase hyphenated strings.

Example UUID: 550e8400-e29b-41d4-a716-446655440000

Release Timeline

What Stays the Same?

• Existing Webhooks: Any webhooks created prior to June 9th will retain their 8-character codes.
• API Endpoints: GET /webhooks/{code}, DELETE /webhooks/{code}, and POST /webhooks/replay remain unchanged.
• Dual Support: Our API will accept both legacy 8-character codes and new UUID codes indefinitely.

Action Required

Please review your integration if you perform any of the following actions:

1. Database Storage: Ensure your storage columns are at least VARCHAR(36). Columns restricted to 8 characters will truncate UUIDs and break lookups.
2. Format Validation: Update any Regex or string-length checks. New codes include hyphens and lowercase letters.
3. Case Sensitivity: Ensure your logic handles lowercase strings.

Migration Examples

Validation Logic

If you validate webhook codes client-side or within your backend, update your logic to support both formats:

C#

public static bool IsValidWebhookCode(string code)
{
    // Check for new UUID format or legacy 8-character hex
    return Guid.TryParse(code, out _) || Regex.IsMatch(code, @"^[0-9A-F]{8}$", RegexOptions.IgnoreCase);
}

JavaScript / TypeScript

import { validate as isUuid } from 'uuid';

const isValidWebhookCode = (code) => {
  return isUuid(code) || /^[0-9A-F]{8}$/i.test(code);
};

Summary of Changes

If you have any questions regarding this transition, please reach out to our support team.