Friendbuy Webhooks

generated: '2026-08-13'
method: searched
source: https://developers.friendbuy.com
spec_type: Webhooks
note: >-
  Friendbuy publishes NO AsyncAPI document — searched the developer docs, the
  friendbuy GitHub org and /asyncapi.yaml on every host, all misses. It does
  publish a full, dated, HMAC-signed webhook + callback catalog in its developer
  documentation, captured here verbatim from that reference. Nothing in this
  file is invented: every event type, payload property and policy below is
  stated on developers.friendbuy.com. Webhooks are configured per account on the
  "Webhooks & Callbacks" tab of the Developer Center in the Retailer App
  (https://retailer.fbot.me).
transport:
  style: http-callback
  method: POST
  direction: friendbuy-to-merchant
  content_type: application/json
  subscriber_endpoint: merchant-supplied URL, configured per webhook in the Retailer App
delivery:
  success_status: 200
  retry:
    policy: Retry every 15 minutes until 24 hours have elapsed or a 200 is received.
    interval: PT15M
    max_duration: PT24H
  timeout:
    seconds: 10
    note: If Friendbuy does not receive a response within 10 seconds the request is aborted; the Retailer App test tool reports 504 for a timed-out call.
  batching: >-
    The `data` property is an ARRAY. Multiple events may be delivered in a
    single webhook call when they occur in quick succession — consumers must
    iterate `data`, never assume one event per request.
  testing: >-
    The "Test Endpoint" button on the Webhooks & Callbacks tab of the Developer
    Center sends a test request to the configured URL and displays the resulting
    status.
security:
  signature_header: X-Friendbuy-Hmac-SHA256
  algorithm: HMAC-SHA256
  encoding: base64
  signed_payload: raw request body
  key: the merchant's Friendbuy secret key
  docs: https://developers.friendbuy.com
envelope:
  properties:
  - {name: id, type: string, description: 'The id of the webhook call; useful for troubleshooting.'}
  - {name: type, type: string, description: 'The event type discriminator; see events below.'}
  - {name: createdOn, type: 'string (ISO 8601 timestamp)', description: The date and time the webhook request was made.}
  - {name: data, type: array, description: 'One or more event payloads; shape depends on type.'}
events:
- name: Advocate Reward
  type: advocateReward
  group: Reward Webhook
  description: >-
    Issued when a referred friend successfully converts and the referring
    advocate earns a reward. The preferred mechanism for depositing credit or
    points into the advocate's account in the merchant's own system.
  data_properties: [rewardId, rewardType, rewardUnit, emailAddress, rewardAmount, createdOn,
    customerId, ipAddress, couponCode, rewardInfo, rewardTrigger, 'friends[]']
  friends_properties: [friendEmailAddress, friendCustomerId, conversionNumber]
- name: Friend Incentive
  type: friendIncentive
  group: Reward Webhook
  description: >-
    Issued when a referred friend successfully converts and earns the friend-side
    incentive. Same envelope as advocateReward; `type` is the discriminator when a
    single endpoint serves both.
  data_properties: [rewardId, rewardType, rewardUnit, emailAddress, rewardAmount, createdOn,
    customerId, ipAddress, couponCode, rewardTrigger, advocateEmailAddress, advocateCustomerId]
- name: Loyalty Reward
  type: loyaltyReward
  group: Reward Webhook
  description: Issued when a loyalty customer completes a loyalty earning event and earns a reward.
  data_properties: [createdOn, customerId, couponCode, emailAddress, ipAddress, rewardId,
    rewardType, rewardUnit, rewardAmount, rewardTrigger]
- name: Email Capture
  type: emailCapture
  description: >-
    Fired when Friendbuy captures an email address (for example a friend
    entering an email to claim an incentive), carrying campaign, referral
    channel/code, advocate and incentive context.
  data_properties: [eventId, emailAddress, name, mobileNumber, 'campaign{id,name}',
    'referral{channel,code}', 'advocate{email,name}', attributionId, 'incentive{couponCode,amount}']
- name: Email Opt-Out
  type: emailOptOut
  description: >-
    Fired when a friend who received an advocate share email clicks the
    unsubscribe link. Friendbuy stops sending share emails to that address for
    all of the merchant's campaigns; the webhook lets the merchant mirror the
    opt-out into their own suppression list.
  data_properties: [emailAddress, campaignId, campaignName]
- name: Receipt
  type: receipt
  description: >-
    Fired when a submitted receipt is processed by receipt scanning, carrying
    the approval status and the parsed store, purchase and line-item detail.
  data_properties: [eventId, receiptId, status, email, customerId, merchantId, storeName,
    storeId, storeAddress, storeCity, storeState, storeCountry, purchaseDate, submissionDate,
    subtotal, total, currency, 'products[]']
- name: Ledger Transaction
  type: ledgerTransaction
  description: Fired when a customer's loyalty ledger balance is credited or debited and the transaction is finalized.
  data_properties: [transactionId, customerId, ledgerCurrency, createdOn, value, ledgerBalance, sourceName, note]
- name: Customer Update
  type: customerUpdate
  description: Fired when a customer's loyalty opt-in status or member tier details change.
  data_properties: [customerId, customerEmail, customerName, 'loyaltyDetails{loyaltyOptInStatus,optedInOn,everOptedIn}',
    'memberTierDetails{memberTierId,memberTierNameCached,memberTierPrecedenceCached,memberTierUpdatedOn}', updatedOn]
callbacks:
- name: Reward Validation Callback
  direction: friendbuy-to-merchant
  method: POST
  description: >-
    Synchronous authorization hook. Before fulfilling a reward, Friendbuy POSTs
    the conversion detail to the Validation URL configured under Reward Criteria
    and uses the merchant's HTTP STATUS CODE as the decision.
  semantics:
    '200': Reward is validated and will be fulfilled.
    '400': Reward is invalidated and will not be fulfilled.
    other: Treated as an error and retried.
  retry:
    policy: Retry every 15 minutes for up to 72 hours, or until the reward is approved or rejected.
    interval: PT15M
    max_duration: PT72H
    on_exhaustion: The reward is rejected and the status noted as an error.
  use_case: Let the merchant's own system veto a reward for returns, cancellations or bespoke fraud rules.
- name: Email Recipient Authorization Callback
  direction: friendbuy-to-merchant
  method: POST
  type: emailAuth
  description: >-
    Fired after an outbound share email passes Friendbuy's own opt-out checks.
    Friendbuy POSTs a list of candidate recipient addresses and the merchant
    responds with which addresses are allowed, applying the merchant's own
    suppression rules on top of Friendbuy's.
  request_properties: [id, type, 'data (array of email address strings)', createdOn]
- name: Visitor Status
  direction: friendbuy-to-browser
  description: >-
    Client-side payload describing the visitor's referral/loyalty status,
    delivered through the Merchant SDK. The docs describe verifying the visitor
    status payload signature before trusting it.
  note: Browser-surface, not an HTTP webhook; recorded for completeness of the event surface.
coverage:
  webhook_events: 8
  callbacks: 3
  asyncapi_published: false