Integrations

Outgoing integrations from RaffleX

N8N Automations

RaffleX provides a native integration with N8N to trigger workflows based on platform events. This guide covers how to configure the integration within your Tenant panel and details the webhook payloads you will receive.

Familiarity to n8n will help with this integration we are currently not providing support for this integration as it is self serve.

Configuration

To set up the N8N integration, navigate to your Tenant Admin Panel:

1. Go to Settings > Integrations.

2. Locate the N8N Integration section.

3. Fill in the following fields:

   • N8N Webhook URL: The URL of your N8N webhook node (e.g., https://n8n.yourdomain.com/webhook/...).

   • N8N Webhook Secret: (Optional) A secret string used to verify the request authenticity. If provided, it will be sent in the X-Webhook-Secret header.

4. Enable the events you wish to subscribe to:

   • Send Order Completed: Triggers when an order is successfully paid and completed.

   • Send User Created: Triggers when a new customer account is registered.

   • Send Marketing Subscribe/Unsubscribe Events: Triggers when a customer subscribes to or unsubscribes from marketing (marketing.subscribed and marketing.unsubscribed).

5. Click Save Settings.

Each toggle is independent. If a toggle is off, or the webhook URL is empty, nothing is sent for that event.

Webhook Structure

All webhooks sent to N8N follow a standard envelope structure:

{
  "event": "order.completed",
  "timestamp": "2024-03-20T10:30:00+00:00",
  "tenant": {
    "id": "tenant_123",
    "domain": "competitions.example.com"
  },
  "data": {
    // Event-specific data
  }
}

Headers

Requests from RaffleX will include the following headers:

• Content-Type: application/json

• X-Webhook-Event: The event type (e.g., order.completed, user.created)

• X-Webhook-Secret: Your configured secret (if set)

---

Event Reference

There are four events in total. Each one is listed below with a full example of the data object you will receive.

Event	Sent when
order.completed	A customer completes a purchase
user.created	A customer registers an account on your site
marketing.subscribed	A customer opts in to marketing
marketing.unsubscribed	A customer is unsubscribed from marketing

Money values are sent as decimal strings in your store currency, for example "10.00" means ten pounds. They are not pennies. The currency field tells you which currency the amounts are in.

1. Order Completed (order.completed)

Triggered when a customer completes a purchase. This fires for every completed order, whatever the payment method used (card, PayPal, wallet credit, free entry, or partial payment). The payment_gateway field in the payload tells you which method was used.

Data Payload:

{
  "order": {
    "id": 1024,
    "status": "completed",
    "subtotal": "10.00",
    "discount": "0.00",
    "credit_used": "0.00",
    "total": "10.00",
    "payment_gateway": "cashflows",
    "discount_code": null,
    "created_at": "2024-03-20T10:30:00+00:00",
    "updated_at": "2024-03-20T10:30:00+00:00"
  },
  "customer": {
    "id": 55,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "[phone]"
  },
  "billing": {
    "street": "123 Raffle Lane",
    "city": "London",
    "county": "Greater London",
    "postcode": "SW1A 1AA",
    "country": "GB"
  },
  "items": [
    {
      "product_title": "Win a PS5",
      "product_slug": "win-a-ps5",
      "quantity": 2,
      "unit_price": "5.00",
      "total": "10.00"
    }
  ],
  "ticket_count": 2,
  "currency": "GBP"
}

2. User Created (user.created)

Triggered when a customer registers an account on your site. It does not fire for accounts you create yourself from the admin panel, or for accounts brought in by an import.

The consent block reflects the state at the moment they registered. If they ticked the marketing opt in box during sign up, marketing_opted_in_at will already be set, as below. If they did not, both fields will be null.

Data Payload:

{
  "user": {
    "id": 55,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "johndoe",
    "created_at": "2024-03-20T10:30:00+00:00"
  },
  "consent": {
    "marketing_opted_in_at": "2024-03-20T10:30:00+00:00",
    "marketing_unsubscribed_at": null
  }
}

3. Marketing Subscribed (marketing.subscribed)

Triggered when a customer opts in to your marketing. This happens when they tick the consent box at checkout, tick the opt in box while registering an account, or enter their email into a newsletter sign up block on your site.

Opting in clears any previous unsubscribe, so marketing_unsubscribed_at is always null on this event.

Data Payload:

{
  "user": {
    "id": 55,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "johndoe",
    "created_at": "2024-03-20T10:30:00+00:00"
  },
  "consent": {
    "marketing_opted_in_at": "2024-03-20T10:30:00+00:00",
    "marketing_unsubscribed_at": null
  }
}

4. Marketing Unsubscribed (marketing.unsubscribed)

Triggered when a customer is unsubscribed from your marketing. This happens when they unsubscribe themselves in My Account, when you unsubscribe them from the Users area of your admin panel, or when they self exclude, whether they do that themselves or you lock their account for them.

Note that marketing_opted_in_at keeps its original value here. It is the date they last opted in, and unsubscribing does not erase it. See How consent is represented below, because this catches people out.

Deleting a customer's account does not send this event. The account is removed first, so there is no customer left to describe by the time the event would be sent. If you use n8n to remove customers from another system, handle account deletions separately rather than relying on this webhook.

Data Payload:

{
  "user": {
    "id": 55,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "display_name": "johndoe",
    "created_at": "2024-03-20T10:30:00+00:00"
  },
  "consent": {
    "marketing_opted_in_at": "2024-03-20T10:30:00+00:00",
    "marketing_unsubscribed_at": "2024-04-02T16:05:00+00:00"
  }
}

---

How consent is represented

Every event that carries a customer includes a consent block, so you never have to guess at their marketing status. It holds two timestamps:

Field	Meaning
marketing_opted_in_at	When the customer last opted in, or null if they never have
marketing_unsubscribed_at	When the customer last unsubscribed, or null if they have not

Read marketing_unsubscribed_at first. This is the bit that catches people out. Opting in and unsubscribing are recorded separately, and unsubscribing does not erase the earlier opt in date. So a customer who opted in during March and unsubscribed in April arrives with both fields set. If you only check marketing_opted_in_at, you will treat an unsubscribed customer as subscribed, and email someone who asked you not to.

The rule to apply is:

1. If marketing_unsubscribed_at is set, the customer is unsubscribed, whatever marketing_opted_in_at says.

2. Otherwise, if marketing_opted_in_at is set, the customer is subscribed.

3. If both are null, the customer has never opted in.

Opting in again clears marketing_unsubscribed_at back to null, so a customer who returns is correctly subscribed once more.

The event field in the envelope (and the matching X-Webhook-Event header) still tells you what just happened, which is handy for routing. The consent block tells you where the customer now stands. Use the event name to decide which branch to run, and the consent block to decide what the customer's state actually is.

Here is a complete marketing.unsubscribed request, envelope included:

{
  "event": "marketing.unsubscribed",
  "timestamp": "2024-04-02T16:05:00+00:00",
  "tenant": {
    "id": "tenant_123",
    "domain": "competitions.example.com"
  },
  "data": {
    "user": {
      "id": 55,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "display_name": "johndoe",
      "created_at": "2024-03-20T10:30:00+00:00"
    },
    "consent": {
      "marketing_opted_in_at": "2024-03-20T10:30:00+00:00",
      "marketing_unsubscribed_at": "2024-04-02T16:05:00+00:00"
    }
  }
}

In n8n, add a Switch node straight after your Webhook node and branch on {{ $json.event }} to route each event type. Use data.user.email as the key to match the customer in whatever system you are updating, and read data.consent to set their status there.

These timestamps are the customer's current state, not a full history. RaffleX keeps the last opt in and the last unsubscribe, so it will not tell you that someone opted in and out four times last year. If you need a complete audit trail, store each event as it arrives. See Klaviyo integration for more on how consent is handled.

---

Delivery and retries

Requests are sent with a 30 second timeout. If your endpoint is unreachable or returns an error, RaffleX retries a small number of times with an increasing gap between attempts before giving up.

This means your workflow can occasionally receive the same event more than once, so build it to cope with repeats. For order.completed, use the order.id to spot an order you have already handled. For the marketing events, use the customer's email address.

Events are not queued up while your endpoint is down. If all the retries fail, that event is lost and will not be sent again later. Keep your n8n instance reachable, and do not rely on these webhooks as your only record of anything important.