Best Practices

Events

Your webhook endpoint should be configured to receive only the types of events required by your integration. Listening for extra events (or all events) will put undue strain on your server and is not recommended.

📘

Events configuration can only be configured by Affirm. Please reach out to Affirm via the support widget.

Whitelists

Affirm uses a number of IP addresses when sending webhook requests and new IPs may be utilized as our systems scale and new resources are brought online. Because of this, we strongly recommend against implementing IP Whitelists for webhook requests as this could cause Affirm's webhook calls to fail.

Retry logic

Affirm does not currently resend (or support retry mechanism) a webhook event if your endpoint did not successfully receive it.

Security

Authentication

We can support Basic Authentication in the URL.

Example: "AB123:[email protected]/affirm_webhook"

Signed Requests

Affirm signs webhook requests so that you can optionally verify that Affirm is sending the request instead of a third-party pretending to be Affirm. Each request includes the following: a base-64 encoded header, and an X-Affirm-Signature. The value of the header is an HMAC-SHA512 hash signature computed from the request payload and your private API key found in your merchant dashboard.

Replay attack prevention

If a third-party intercepts a request payload and its signature, your endpoint is susceptible to a replay attack. To mitigate these attacks, we include a timestamp in the X-Affirm-Signature header. Since the timestamp is part of the signed payload, the attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is old, you should reject the request. We recommend rejecting a response with a timestamp 5 minutes older than the current time.