Webhooks

Webhook nodes provide the ability for you to send information about a customer in a journey
to external services. When a webhook node is processed, a payload is sent to the specified URL
with information about the journey and journey node it came from, as well as information about the
customer and session currently being processed by that node.

This can allow you to build a receiver that can be notified when a customer has reached a point in their journey, which would allow you to do whatever you'd like, including notifying other
software with updates about the customer.

Payload

The payload for webhook nodes consists of a complete picture of the customer, session, and their current
status within a journey. The payload is always JSON format. A description of the fields of the payload is below:

Top-Level Fields

Site

Customer

Cart

CartItem

Contact

CustomerJourney

Journey

JourneyNode

Session

Product

Sample Payload

{
    "site": {
        "id": "abcdefg",
        "url": "http://example.com",
        "currency": "USD",
        "timezone": "America/New_York"
    },
    "customer": {
        "id": "abcdefg",
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "867-5309",
        "gender": "m",
        "timezone": "America/New_York",
        "age": 30,
        "language": "en",
        "country": "USA",
        "tags": ["foo", "bar"],
        "address1": "",
        "address2": "",
        "address3": "",
        "city": "",
        "state": "",
        "postal_code": "",
        "birthdate": null
    },
    "cart": {
        "cart_items": [],
        "item_count": 4,
        "metadata": {},
        "order_number": "12345678910",
        "promo": "PROMO",
        "return_url": "http://example.com/cart/",
        "value": 4000
    },
    "contact": null,
    "customer_journey": {
        "id": "abcdefg",
        "finish_date": null,
        "start_date": "2019-01-01T10:30:00"
    },
    "journey": {
        "id": "abcdefg",
        "name": "Cart Abandon",
        "options": "",
        "trigger": "Cart Abandon"
    },
    "journey_node": {
        "id": "abcdefg",
        "action": "Send Webhook",
        "audience": {
            "id": "abcdefg",
            "action": "Audience",
            "display": "Catch-All"
        }
    },
    "metadata": {
        "custom_webhook": "metadata",
        "foo": "bar"
    },
    "session": {
        "abandon_date": "2019-01-01T11:30:00",
        "convert_date": null,
        "delivery_date": null,
        "fulfillment_date": null,
        "id": "12345678910",
        "metadata": {},
        "payment_date": null,
        "start_date": "2019-01-01T10:30:00",
        "status": "abandoned_cart",
        "viewed_products": [
            {
                "date": "2019-01-01T10:30:00",
                "product": {
                    "categories": ["default", "test"],
                    "description": "This is a test product.",
                    "expiration_date": null,
                    "image_url": "http://via.placeholder.com/150",
                    "name": "Test Product",
                    "price": 3400,
                    "product_id": "ProductID-0",
                    "product_url": "http://example.com/test-product"
                }
            }
        ]
    }
}

Webhook Signatures

All webhooks are signed using a secret key unique to your site which you can
use to verify that the payload has not been tampered with. This is not strictly
necessary but is recommended to ensure the accuracy of your data.

Rejoiner generates signatures using a hash-based message authentication code
(HMAC) and SHA-1. You can verify a signature
by following these steps:

1. Extract the timestamp and the signature from the X-RJ-Signature header on the request.
   The timestamp value is prefaced with t= and the signature value is prefaced with sha1=.

2. Prepare the signed payload string. The payload used to generate the signature can be generated by concatenating the following:
   

   • The timestamp value extracted from the header
   • The period character: `.`
   • The actual JSON payload of the request (i.e. the request body)

3. Generate the signature by computing an HMAC with your site's webhook secret as
   the key and the signed payload string as the message.

4. Compare your generated signature with the signature in the request. If the two
   signatures match, then compare the current timestamp with the request's timestamp
   and decide if the difference between them is within your tolerance.

Retries and Rate Limits

Rejoiner will attempt to send a webhook up to 5 times until it succeeds. A webhook
is considered to be successfully delivered if it receives a 2xx response from
your server. If any other response is returned, the webhook will be retried with
exponential backoff to avoid sending too many messages at once that may fail.

Additionally, if your endpoint results in greater than an 80% failure rate within
one hour, Rejoiner will only attempt to send a webhook once. This is done to avoid
sending too many messages to a non-responsive server by retrying every failed message
but to still allow messages to be received if a server comes back online.