Notify Enrollment

Enrollment webhooks allow you to be notified of enrollment for your users. Your marketplace should expose an HTTPS endpoint that accepts a POST of a JSON document encoded in the UTF-8 character encoding. Cardlytics will publish an enrollment notification to this endpoint each time a enrollment changes state.

Enrollment Event States

State	Final State?	Description
ENROLLMENT_CONFIRMED	No	This state is triggered when a user (card) has been sucessfully enrolled with Cardlytics for the marketplace
ENROLLMENT_TERMINATED	No	This state is triggered when a request has been been processed to disenroll a card with Cardlytics for the marketplace

Enrollment Event Body Format

Field	Example	Description
eventId	11111111-1111-1111-1111-111111111111	The unique id of the event. Each event will have a unique event id.
event	one of: ENROLLMENT_CONFIRMED, ENROLLMENT_TERMINATED	The enrollment event type.
eventTimestamp	2021-04-29T11:06:55.000Z	ISO 8601 formatted timestamp representing when the event happened.
notificationTimestamp	2012-04-29T11:15:55.000Z	ISO 8601 formatted timestamp representing when the event was sent to your configured webhook.
userId	00000000-0000-0000-0000-000000000000	This is your marketplace’s unique identifier for your user. Supports an id up to 36 characters.
paymentNetworkId	one of: VISA, MASTERCARD, AMEX, DISCOVER, PAYPAL	The payment network the card belongs to
cardId	00000000-0000-0000-0000-000000000000	This is the payment network’s identifier for the card.
cardLastFour	1234	This is the original card last4 that was passed when notifying Cardlytics about the enrollment.

Example:

{
  "eventId": "11111111-1111-1111-1111-111111111111",
  "event": "ENROLLMENT_CONFIRMED",
  "eventTimestamp": "2021-04-29T11:06:55.000Z",
  "notificationTimestamp": "2021-04-29T11:15:55.000Z",
  "userId": "00000000-0000-0000-0000-000000000000",
  "cardId": "22222222-2222-2222-2222-222222222222",
  "cardLastFour": "1234",
  "paymentNetworkId": "VISA"
}

Endpoint Delivery Semantics

Your endpoint should be idempotent. Cardlytics guarantees at-least-once delivery policies for each event. You may use the eventId of an event to help with idempotency as every event Cardlytics sends will have a unique eventId. The eventId for a given event does not change and will be used for all subsequent retries to send the event to your webhook.

Acknowledgment and Error Handling

Once you have successfully received an enrollment notification, your endpoint should return a 200 HTTP status code.

While 301 and 302 HTTP status codes are both supported be aware we will only follow a redirect once.

All other status codes will be considered an error. For debugging purposes we recommend that partners follow the HTTP spec:

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
500 Internal Server Error
501 Not Implemented
503 Service Unavailable

Timeout

Your endpoint must respond within 20 seconds or it will be considered an unsuccessful delivery attempt.

Event Retry Handling

Delivery of a webhook payload is considered to have failed when Cardlytics does not receive a response with an HTTP status code of 200 within 20 seconds of sending. Cardlytics will automatically resend notifications multiple times before marking it as failure.

The best-effort retries are set to happen like so:

2 retries - 30 seconds after the last failed attempt
3 retries - 5 minutes after the last failed attempt
12 retries - 1 hour after the last failed attempt

For example if your webhook is down for 24 hours, Cardlytics will try to send the payload up to 18 times. The number of times and the timeout window are subject to change, so you should not write code relying on the explicit number.

Attempt	Request type	Time	HTTP Response
1	Initial request	~ 01:00:00	`500`
2	30 second retry	~ 01:00:30	`500`
3	30 second retry	~ 01:01:00	`500`
4	5 minutes retry	~ 01:06:00	`500`
5	5 minutes retry	~ 01:11:00	`500`
6	5 minutes retry	~ 01:16:00	`500`
7	1 hour retry	~ 02:16:00	`500`
8	1 hour retry	~ 03:16:00	`500`
...	...	...	...
18	1 hour retry	~ 13:16:00	`500`

Security

The endpoints you expose and that Cardlytics exposes are available over the public internet. To validate that the request originated from an authenticated client, all requests include a JWT which attests to the authenticity of the request. For more details, see: the API Reference: Overview: Cardlytics JWT Authorization Token.

Originating IP Addresses

Cardlytics requests will always originate from the following IP addresses:

34.200.22.120
54.144.103.20
54.235.87.177