Automating External ID Assignment Using Tulip Webhooks

This guide outlines a robust integration pattern for automatically assigning an externalId from your system to a resource (e.g., a Customer, Order) as soon as it’s created in Tulip.

This process utilizes a “round-trip” workflow where Tulip notifies your application of a new resource, and your application responds by updating that resource with a unique identifier from your ecosystem.

Core Concept

The workflow is event-driven and follows these logical steps:

  1. Trigger: A resource is created in Tulip.
  2. Notify: Tulip sends a webhook notification to your external service with the new resource’s unique Tulip ID (uuid).
  3. Process: Your service receives the notification, generates or retrieves an externalId.
  4. Update: Your service makes an API call back to Tulip to update the original resource, setting its externalId.

Prerequisites

  • Administrative access to your Tulip Admin Console.
  • An external application or service with an endpoint capable of receiving HTTP POST requests.
  • API credentials for your Tulip environment to authorize the update call.

Step-by-Step Implementation

Step 1: Create the Webhook Subscription in Tulip

First, you need to tell Tulip where to send notifications when a new resource is created.

  1. Log into your Tulip Admin Console.
  2. Navigate to Integrations → Webhook Subscriptions.
  3. Click Create New Webhook.
  4. Configure the subscription with the following settings:
  • Is Active: ON
  • URL: The URL of your external service’s endpoint that will receive the webhook.
  • Event Type: Select the appropriate creation event, for example, customerCreate.
  • Authentication Method: Choose the method your endpoint requires (None, Basic, or Bearer).
  1. Click Save.

Step 2: Receive the Webhook Event

When a new customer is created in Tulip, Tulip will send a POST request to the URL you configured. Your service needs to be ready to handle this request.

The JSON payload will look similar to this:

{
  "uuid" : "03a4eabd-2551-41d9-9828-e105b1eb5cf5",
  "subscription": "1fec24e8-f02c-4ff6-a1a5-37bbdac42b1b",
  "createdAt":"2022-06-15T13:45:30Z",
  "eventType": "customerCreate",
  "resourceType":"Customer",
  "resource": {
    "uuid": "05c443ae-3edf-42e1-b4f9-f5a819252c0e",
    "externalId": null
  },
  "source": "TULIP-APP"
}

Important: The most critical piece of data here is the resource.uuid. This is the unique identifier you will use to update the customer record in the next step.

Step 3: Process the Event and Update Tulip

Your endpoint’s logic should perform the following actions:

  1. Acknowledge Receipt: Immediately respond to Tulip’s POST request with a 2xx HTTP status code (e.g., 200 OK). This confirms receipt and prevents Tulip from attempting to retry the delivery.

  2. Extract the UUID: Parse the incoming JSON payload to get the resource.uuid.

  • From the example above: 05c443ae-3edf-42e1-b4f9-f5a819252c0e.
  1. Generate an External ID: Implement your business logic to generate a new externalId or retrieve it from another system (e.g., your central ERP or master database).
  • Example generated ID: cust-ext-98765.
  1. Call the Tulip API: Make an authenticated API call back to Tulip to update the customer.
  • HTTP Method: PATCH or PUT
  • Endpoint: /api/{version}/crm/customers/{id} (as specified in the documentation).
  • URL: Replace {id} with the uuid you extracted.
    • Example: https://<your-tulip-environment>.tulip.com/api/v2/crm/customers/05c443ae-3edf-42e1-b4f9-f5a819252c0e
  • Request Body: Include the externalId in the JSON body.
{
  "externalId": "cust-ext-98765"
}

By following this pattern, you can ensure that all new resources created in Tulip are automatically and reliably tagged with an identifier from your external systems, enabling seamless data synchronization.

← What's New