Recipient Webhooks

Webhooks are an HTTP POST message sent from the BitPay server to the merchant’s eCommerce server. The primary purpose of a webhook is to alert the merchant’s ecommerce server that the status of a resource (invoice, payout, and now recipients) has changed. The messages are sent to the notificationURL field when creating the invoice or payout request.

Handling

BitPay does not sign webhooks, so the information in the payload should never be trusted outright:

The webhook shall be used by the merchant as a trigger to verify the status of a specific
recipient. This can be done by retrieving the corresponding recipient object, via the GET
recipients/recipientId endpoint (recipientId will be provided in the body of the webhook).
Merchants will be waiting for the "active" status for a given recipient before they include them on a payout batch
The BitPay server expects an HTTP 200 response with an empty body to the webhook. Any other response is considered by BitPay as a failed delivery.
Merchants must use HTTPS for the notificationURL.
The BitPay server attempts to send webhooks multiple times until the send is either successful or the BitPay server gives up. (schedule to be defined).

Headers

Header	Value
Accept	application/json
Content-Type	application/json

Body

Name	Description	Type
event	Webhook event object.	`object`
→ code	See the list of available Webhook notification codes for more information.	`number`
→ name	See the list of available Webhook notification codes for more information.	`string`
data	Webhook data object, containing the recipient information.	`object`
→ id	Unique recipient id assigned by BitPay for a given customer email.	`string`
→ shopperId	This is the unique id assigned by BitPay if the shopper used his personal BitPay account to authenticate and pay an invoice. For customers signing up for a brand new BitPay personal account, this id will only be created as part of the payout onboarding. The same field would also be available on paid invoices if the customer signed in with his BitPay personal account before completing the payment. This can allow merchants to monitor the activity of a customer deposits & payouts).	`string`
→ email	Recipient email address to which the invite link shall be sent.	`string`
→ status	Recipient status, can have the following values: `"invited"`, `"unverified"`, `"verified"`, `"active"`, `"paused"`, `"removed"`	`string`
→ label	For merchant use, pass through - could be customer name or unique reference ID.	`string`

Webhook notification codes

Code	Name	Purpose
4001	`"recipient_invited"`	To notify merchants that a recipient has reached the status
`"invited"`
4002	`"recipient_unverified"`	To notify merchants that a recipient has reached the status
`"unverified"`
4003	`"recipient_verified"`	To notify merchants that a recipient has reached the status
`"verified"`
4004	`"recipient_active"`	To notify merchants that a recipient has reached the status
`"active"`
4005	`"recipient_paused"`	To notify merchants that a recipient has reached the status
`"paused"`
4006	`"recipient_removed"`	To notify merchants that a recipient has reached the status
`"removed"`
4007	`"recipient_manuallyNotified"`	Whenever a merchant request for the last notification to be resent

HTTP Response

{
    "event":{
        "code":4003,
        "name":"recipient_verified"
    },
    "data":{
        "id":"8Gq174SFAnQpdLDxRZCBPB",
        "shopperId":"5QZnQKyanj8o7qohDf2zC2",
        "email":"[email protected]",
        "label":"updatedLabel",
        "status":"verified"
    }
}