Sending webhook data to external systems

Prerequisite: You must have an active webhook subscription listening for an event type inside Tulip and a webhook endpoint able to receive webhook requests from Tulip. Steps on how to create a webhook subscription inside Tulip can be found in Subscribing to Events page.

1. When an event occurs inside Tulip, a process sends event data to the subscribed webhook endpoint (integrator system)

2. Tulip builds the event data to send to the webhook endpoint. Event data will be sent in the request body payload in JSON format. Example of the event data schema can be found here.

3. HTTP POST request(s) are sent to the webhook subscription url configured during setup. This request will enforce the authentication method set for this subscription and implement Hash-based Message Authentication (HAMC) for added webhook security.

4. Example POST request here with Bearer as selected authentication method:

curl -X POST https://your-webhook-url.com
   -H "Accept: application/json"
   -H "X-Tulip-Hmac-256": e4ad0102dc2523443333d808b91a989b71c2439d7362aca6538d49f76baaa5ca"
   -H "X-Webhook-Version": "2022-08"
   -H "Authorization: Bearer {token-set-in-Tulip-Admin-Console}"
   -d "{
      "uuid" : "03a4eabd-2551-41d9-9828-e105b1eb5cf5",
      "subscription": "1fec24e8-f02c-4ff6-a1a5-37bbdac42b1b",
      "createdAt":"2022-06-15T13:45:30",
      "eventType": "customerCreate",
      "resourceType":"Customer",
      "resource": {
        "uuid": "05c443ae-3edf-42e1-b4f9-f5a819252c0e",
        "externalId": "some-external-id"
      },
      "source": "TULIP-APP",
}"

Retries and Failures#

Failures can occur when making a `POST`` call to the webhook URL for the following reasons:

• Network connection error
• Server Error
• Timeout Error
• Non 2xx response from the server

If a failure occurs when making a POST call to the webhook URL specified in the subscription, the event will be re-queued in the stack to be processed again. The retires are implemented with exponential backoff. The retry schedule is:

1. 5 seconds
2. 20 seconds
3. 125 seconds

Viewing logs for webhook requests#

You are able to monitor the status of webhook POST requests through the Admin Console → Integrations → Webhooks Logs page.