N8n Webhook Integration

Complete technical guide for connecting your N8n workflows to the Giftias platform via automated webhooks. Use this API to programmatically create and update localized gift guides.

Authentication

All webhook requests must be authenticated using an API key. You must include your secret API key in the headers of your request using the X-API-Key header.

⚠️ Security WarningKeep your API key secret. Never expose it in client-side code, public repositories, or share it with unauthorized users. If compromised, regenerate it immediately in the Admin Settings.

Example cURL Request

bash

curl -X POST https://api.giftias.com/v1/webhooks/n8n/incoming \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_secret_api_key_here" \
  -d '{
    "event": "gift_guide_created",
    "data": { ... }
  }'

Webhook Endpoint

Configure your N8n HTTP Request node to send a POST request to this URL.

POST

https://api.giftias.com/v1/webhooks/n8n/incoming

Data Schema Requirements

The Giftias platform relies heavily on localized content to serve our global audience. Every text field must be provided as an object containing translations for our 7 supported languages.

Image Requirements

Use absolute, publicly accessible HTTPS URLs.
Recommended hero image ratio: 16:9 (min 1200x675px).
Recommended item image ratio: 1:1 (min 600x600px).
Supported formats: JPG, PNG, WebP.

Price Formats

Prices are passed as strings to preserve formatting.
Always include the currency symbol/code (e.g., "45.00 PLN", "12 €").
Localize the format where applicable (e.g., dot vs comma decimal separators).

Field	Type	Required	Description
event	String	Yes	Must be exactly `gift_guide_created`
data.slug	Object	Yes	URL-friendly identifiers for each language.
data.title	Object	Yes	Localized display title for the guide.
data.heroImageUrl	String	No	Absolute URL for the guide's main header image.
data.giftItems	Array	Yes	Array of gift item objects (see example for internal structure).

Example JSON Payload

This is a complete, valid payload demonstrating a gift guide creation.

json

{
  "event": "gift_guide_created",
  "data": {
    "slug": {
      "en": "gift-for-woman-under-100-pln",
      "en-us": "gift-for-woman-under-100-pln",
      "pl": "prezent-dla-kobiety-do-100-zl",
      "de": "geschenk-fur-frauen-unter-100-pln",
      "fr": "cadeau-pour-femme-moins-de-100-pln",
      "es": "regalo-para-mujer-menos-de-100-pln",
      "uk": "podarunok-dlya-zhinky-do-100-pln"
    },
    "title": {
      "en": "Best Gifts for Women Under 100 PLN",
      "en-us": "Best Gifts for Women Under 100 PLN",
      "pl": "Najlepsze Prezenty dla Kobiety do 100 zł",
      "de": "Beste Geschenke für Frauen unter 100 PLN",
      "fr": "Meilleurs Cadeaux pour Femmes à moins de 100 PLN",
      "es": "Mejores Regalos para Mujeres por menos de 100 PLN",
      "uk": "Найкращі подарунки для жінок до 100 злотих"
    },
    "description": {
      "en": "A curated collection of thoughtful and elegant gifts that won't break the bank.",
      "en-us": "A curated collection of thoughtful and elegant gifts that won't break the bank.",
      "pl": "Wyselekcjonowana kolekcja przemyślanych i eleganckich prezentów, które nie zrujnują budżetu.",
      "de": "Eine kuratierte Sammlung durchdachter und eleganter Geschenke.",
      "fr": "Une collection de cadeaux attentionnés et élégants qui ne ruineront pas votre budget.",
      "es": "Una colección seleccionada de regalos elegantes y pensados que no romperán el banco.",
      "uk": "Колекція продуманих та елегантних подарунків, які не вдарять по бюджету."
    },
    "heroImageUrl": "https://example.com/images/hero-woman-gifts.jpg",
    "giftItems": [
      {
        "id": "item-001",
        "name": {
          "en": "Scented Soy Candle",
          "en-us": "Scented Soy Candle",
          "pl": "Świeca Sojowa Zapachowa",
          "de": "Duftende Sojakerze",
          "fr": "Bougie Parfumée au Soja",
          "es": "Vela de Soja Perfumada",
          "uk": "Ароматична соєва свічка"
        },
        "price": {
          "en": "45.00 PLN",
          "en-us": "45.00 PLN",
          "pl": "45,00 zł",
          "de": "45,00 PLN",
          "fr": "45,00 PLN",
          "es": "45,00 PLN",
          "uk": "45,00 PLN"
        },
        "description": {
          "en": "Hand-poured soy candle with relaxing lavender scent. Burn time: 40 hours.",
          "en-us": "Hand-poured soy candle with relaxing lavender scent. Burn time: 40 hours.",
          "pl": "Ręcznie zalewana świeca sojowa o zapachu lawendy. Czas palenia: 40 godzin.",
          "de": "Handgegossene Sojakerze mit entspannendem Lavendelduft.",
          "fr": "Bougie en cire de soja coulée à la main avec parfum relaxant de lavande.",
          "es": "Vela de soja vertida a mano con relajante aroma a lavanda.",
          "uk": "Соєва свічка ручної роботи з розслаблюючим ароматом лаванди."
        },
        "image": "https://example.com/images/candle-lavender.jpg",
        "affiliateUrl": "https://store.example.com/candle?ref=giftias"
      }
    ]
  }
}

N8n Configuration Guide

Add an HTTP Request Node

In your N8n workflow, add an HTTP Request node where you want to trigger the gift guide creation.

Configure Request Parameters

Method: POST
URL: https://api.giftias.com/v1/webhooks/n8n/incoming
Send Headers: True
Headers: Name: X-API-Key, Value: Your API Key
Send Body: True
Body Content Type: JSON

Map Your Data

In the JSON parameter, construct your payload. You can use N8n expressions to dynamically map data from previous nodes.

{ "event": "gift_guide_created", "data": { "title": { "en": "={{ $json.englishTitle }}", "pl": "={{ $json.polishTitle }}" } } }

Test and Verify

Execute the node. A successful response will return a 200 OK or 201 Created status. If you receive a 401 Unauthorized, verify your API key is correct.