Affirm uses webhooks to notify your application any time events happen.
Webhook endpoints are not self-serve. Please reach out to us via the support widget.
Affirm creates an checkout event object for each occurrence that’s worth notifying you about, like a new checkout from a customer, or a confirmed checkout. Each event has its own status.
When you create a webhook endpoint, it normally listens for specific events, then takes action whenever those events are being received. Technically, a webhook endpoint is hosted on your server-side code (e.g in python, node,etc.), that handles any push from third and/or specific parties.
About Affirm's Webhooks
Affirm will send an HTTP POST
request to a URL that you provide to us. That URL should be a page or endpoint that you've set up to receive requests from our servers.
Merchants can't add a webhook endpoint or manage events by themselves via Affirm Dashboard. Please reach out to us via the support widget for details.
Affirm policies
Customers must opt-in for the approval decisions to be included. The confirmed event is the only webhook event that is guaranteed to be present for each successful Affirm checkout attempt. All other events (approved/not approved/etc.) will only be present if the customer has opted into the Affirm data sharing policy. Customers are actively prompted to enable data sharing, and they can toggle this setting ("Personalized Services") in their Affirm'suser profile at any time.
Endpoint requirements
- HTTP/HTTPS
- Receives POST method
- Returns 20x status
- Support TLS 1.2 (self-signed or expired certificates are not accepted)
- Rate dependent on merchant checkout traffic
- Inbound IP is dynamic
- Content-Type: application/x-www-form-urlencoded
- Accept-Encoding: gzip
Webhook Request Properties
- POST method
- User-Agent: Affirm-Webhook
- Origin IP is dynamic
Respond to a webhook event
Your endpoint should respond to Affirm with a 2xx status code to communicate that you successfully received the webhook event notification. Affirm will treat all other response types as a failed delivery, including 3xx status codes. This means that we will treat URL redirections and "Not Modified" responses as failures. Affirm will ignore any other information returned in the request headers or request body.
Affirm doesn't currently resend a webhook event if your endpoint didn't successfully receive it.
Webhook events
Checkout events
When your customers go through the Affirm's checkout flow, you can receive different checkout status events in real-time via your webhook endpoint.
- Enters checkout.
- Receives a credit decision.
- Confirms their loan.
User experience | Affirm event | Webhook event |
---|---|---|
Selects Affirm as payment option and is sent to Affirm | Checkout created | opened |
Creates or signs into an Affirm account | None | None |
Processing Screen | Approval decision | - approved- not_approved- more_information_need` |
Selects loan terms and agrees to disclosures | none | none |
Clicks confirm and is sent back to merchant site | Checkout confirmation | confirmed |
Prequal events
When your customers go through the Affirm's prequalification flow, you can receive different prequalification status events via your webhook endpoint.
- Clicks the See if you qualify button in the Learn More modal.
- Receives a credit decision.
- The prequalification expires.
User experience | Affirm event | Webhook event |
---|---|---|
Customer clicks the “See if you qualify” button in the “Learn More” modal | Prequalification Triggered | opened |
Creates or signs into an Affirm account | None | None |
Processing Screen | Approval decision | prequal_decision |
Prequalification expires, could occur within up to 7 days later | Prequalification Expiration | None |
When to use webhooks
Webhooks are optional but sometimes preferred for behind-the-scenes or asynchronous transactions, like In-store integration since we are waiting on the customer to complete their checkout to receive the checkout_id
. In APIs like these, Affirm needs to notify your integration about changes to the status of the object so that you can act on them.
Some Affirm requests (e.g., checkout or prequalification) generate events that Affirm catches. These events allow you to share information with other systems as well. You can also use webhooks to automate business tasks:
- Performance metrics (e.g funnel conversion, etc.)
- Streamline and automate operation processes
Webhook requirements
While the requests sent from Affirm to your webhook endpoint comes with the
content-type
application/x-www-form-urlencoded
, the request gives both anapplication/x-www-form-urlencoded
andJSON
version of the data in the bodyRaw and body fields respectively.
Including a session ID in the webhook response
You can include a session ID in the webhook responses by including the session ID in the checkout object that is sent or by including a session ID in affirm.js.
To include the session ID is affirm.js, follow the format included in the example below:
_affirm_config =
{ public_api_key: "YOUR_PUBLIC_KEY",
script: "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
session_id: "YOUR_VISITOR_SESSION_ID" }
Updated 4 months ago
Related topics
Checking webhook signatures |
Best practices |