📤 Outgoing Webhooks

Outgoing webhooks notify your external services in real time about specific events in Brighty system, such as account changes, card status updates, member data changes, and more.

---

⚙️ Webhook Registration

Webhooks are configured via the Business Settings UI.

To register a webhook, submit the following:

• url: HTTPS endpoint to receive event POST requests.
• secret (optional): HMAC key for signature validation. If omitted, one will be securely generated server-side.

After registration, you can choose which event types to subscribe to for that webhook.

---

🔔 Event Structure

All webhook payloads follow a shared structure:

{
  "id": "c6e7a08c-527f-4d12-9847-bb46944f3e92",
  "eventName": "ACCOUNT.CREATED",
  "occurredAt": "2025-07-04T10:12:34Z",
  "payload": {
    // See payload types below
  }
}

• eventName uses the format: ENTITY.EVENT_TYPE
• occurredAt is in ISO 8601 UTC format
• payload varies by entity

---

🧬 Payload Types

ACCOUNT Events

Event types: CREATED, FUNDS_BLOCKED, FUNDS_DEPOSITED, FUNDS_HELD, FUNDS_RELEASED, FUNDS_UNHELD, FUNDS_WITHDRAWN, PURPOSE_CHANGED, TERMINATED

Example payload:

{
  "accountId": "2e6ff734-e2cf-4e53-9829-56c2f62d0671",
  "name": "Main account",
  "balance": {
    "amount": "1000.00",
    "currency": "EUR"
  },
  "accountType": "CURRENT",
  "openedAt": "2024-10-15T09:01:00Z"
}

---

CARD Events

Event types: CREATED, ISSUED, ACTIVATED, FROZEN, UNFROZEN, TERMINATED, CARDHOLDER_NAME_CHANGED, SPENDING_LIMIT_POLICY_CHANGED, SECURITY_POLICY_CHANGED

Example payload:

{
  "cardId": "3f256c5e-9407-4c10-bdb9-3a87a9b86c32",
  "cardOwnerId": "0e84a582-5a71-476c-a44d-2e9223fbe3be",
  "cardHolderId": "2b9b65db-cdb4-4c4c-91f8-d1c0ef9c2297",
  "status": "ACTIVE",
  "statusReason": null,
  "name": "Company Debit",
  "cardType": "DEBIT",
  "network": "MASTERCARD",
  "formFactor": "VIRTUAL",
  "lastFour": "1234"
}

---

MEMBER Events

Event types: CREATED, OFFBOARDED, SUSPENDED, NAME_CHANGED, USERNAME_CHANGED, PICTURE_CHANGED, ADDRESS_CHANGED, RESIDENCE_CHANGED, BIRTH_INFO_CHANGED, LEGAL_SEX_CHANGED, NATIONALITY_CHANGED, EMAIL_SET, EMAIL_CONFIRMED, PHONE_SET, PHONE_CONFIRMED

Payloads vary by events:

Customer Profile events

CREATED, OFFBOARDED, SUSPENDED, USERNAME_CHANGED, PICTURE_CHANGED

{
  "memberId": "be6d34ae-4c45-41d7-9c92-2aa2a7991dc5",
  "customer": {
    "id": "a0ec0d71-2069-4562-a2b0-8a89cb8de913",
    "username": "jdoe",
    "name": "John Doe",
    "picture": "https://example.com/avatar.png"
  }
}

Contact Info events

EMAIL_SET, EMAIL_CONFIRMED, PHONE_SET, PHONE_CONFIRMED

{
  "memberId": "be6d34ae-4c45-41d7-9c92-2aa2a7991dc5",
  "contactInfo": {
    "email": "jdoe@example.com",
    "phone": "+66812345678"
  }
}

Legal Data events

NAME_CHANGED, ADDRESS_CHANGED, RESIDENCE_CHANGED, BIRTH_INFO_CHANGED, LEGAL_SEX_CHANGED, NATIONALITY_CHANGED

{
  "memberId": "be6d34ae-4c45-41d7-9c92-2aa2a7991dc5",
  "legalData": {
    "name": {
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null
    },
    "address": {
      "streetLine1": "Passeio do Levante",
      "city": "Lisbon",
      "region": "Lisbon",
      "zipCode": "1990-503",
      "country": "PT"
    },
    "birthInfo": {
      "birthDate": "1990-05-10",
      "birthPlace": {
        "city": "Lisbon",
        "country": "PT"
      }
    },
    "legalSex": "M",
    "countryOfResidence": "PT",
    "nationality": "PT"
  }
}

---

THREE_DS Events

Event types: CREATED, APPROVED, DECLINED

Example payload:

{
  "threeDSId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cardOwner": "bdf927d1-740c-4577-81a0-35638a713775",
  "requestId": "req_001",
  "merchantId": "2fd8d990-5b89-47a1-99c1-f6b458309a68",
  "amount": {
    "amount": "30.00",
    "currency": "EUR"
  },
  "cardId": "7c3c8f10-83f2-487e-9423-d17cc3a8a53b",
  "cardToken": "card_tok_abc123",
  "lastFour": "5678",
  "threeDSType": "PUSH",
  "createdAt": "2025-07-04T09:22:11Z",
  "lifeTimeInSec": 300,
  "publicUrl": "https://examlpe.com/3ds/124354"
}

---

TRANSACTION Events

Event types: CREATED, COMPLETED, CANCELED

Example payload:

{
  "transactionId": "a5e53fb9-1f4d-4c4f-a6b2-915879e51ab0",
  "transactionType": "CARD_PAYMENT",
  "createdAt": "2025-07-03T17:30:00Z",
  "completedAt": "2025-07-03T17:32:00Z",
  "canceledAt": null,
  "cancellationReason": null,
  "subtype": "CARD_ORDER",
  "amount": {
    "amount": "150.00",
    "currency": "EUR"
  }
}

---

PAYOUT Events

Event types: CREATED, COMPLETED, CANCELED

Example payload:

{
  "payoutId": "a5e53fb9-1f4d-4c4f-a6b2-915879e51ab0",
  "name": "Salary July",
  "createdAt": "2025-07-03T17:30:00Z"
}

---

🔐 Signature Verification

All webhook requests are signed using HMAC-SHA256 and Base64-encoded.

Two headers are included:

Header	Description
x-timestamp	Epoch milliseconds at time of signing
x-signature	Base64-encoded HMAC of the signed data string

Signature String

The signature is generated as:

HMAC_SHA256(secret, "$timestamp.$eventJson")

Where:

• timestamp is the value of the x-timestamp header (epoch millis)
• eventJson is the exact stringified JSON body of the request

Compare the result (Base64-encoded) with the x-signature header to verify authenticity.

---

🔁 Retry Policy

Webhook delivery follows an exponential backoff retry strategy:

Attempt	Delay
1	5 minutes
2	1 hour
3	5 hours
4+	18 hours

• A retry is triggered on non-2xx responses or timeouts.