Although most user events occur when the user interacts with your Embeddable, meaning Embeddables will automatically capture that event, there are times when user events occur elsewhere. For example, a user completing a doctor’s appointment, or a user completing a purchase that isn’t handled by Embeddables’ Stripe integration. In those cases, you can send data to the Embeddables API using a server-side request.

​
How to send data to Embeddables

1

Generate an Embeddables API key

  • Contact the Embeddables team to generate an API key for your project.
  • API keys are Restricted Keys, and always start with rk_ - for example: rk_myexampleapikey.
2

Prepare your event data

  • Create a JSON object with the following required fields:
    • embeddable_id: The ID of your Embeddable
    • timestamp: The time the event occurred (in ISO 8601 format)
    • custom_event_name: A name for your custom event (must be snake_case)
    • custom_event_props: Any custom properties as a JSON string
    • identifiers: A list of key-value pairs to identify the user (e.g., email)
The identifiers field is an array of objects, each containing a key and value. Currently, we only support one identifier per request (i.e. one object in the array).
Watch out for this: The value field must be a stringified JSON value. E.g. for email addresses, the value must be "\"test@test.com\"" (note the double quotes).
3

Send the event to the API

  • Make a POST request to /projects/{projectId}/events
  • Include your API key in the X-Api-Key header
  • Send the event data in the request body
Example request:
curl -X POST https://api.embeddables.com/projects/pr_myexampleproject/events \
  -H "X-Api-Key: rk_myexampleapikey" \
  -H "Content-Type: application/json" \
  -d '{
    "embeddable_id": "flow_myexampleflow",
    "timestamp": "2022-01-01T00:00:00.000Z",
    "custom_event_name": "my_custom_event",
    "custom_event_props": "{\"my_prop\": \"my_val\"}",
    "identifiers": [
      {
        "key": "email",
        "value": "\"test@test.com\""
      }
    ]
  }'
The API will return a 200 status code if the event was successfully created. If there are any issues with the request (e.g., invalid API key, missing required fields), you’ll receive an appropriate error response.

​
Troubleshooting

​
I’m getting a 404 ENTRY_NOT_FOUND response

This means that the Embeddables API is trying to find a user that matches the identifiers you provided, for the embeddable_id you provided, but couldn’t find one. Things to look out for:
  1. Check that you are passing the correct embeddable_id - this should be the ID of the Embeddable that matches the user you’re trying to add an event for.
  2. Check that you are passing the correct key inside identifiers - this should be the key in the User Data that matches the input component that the user typed in, such as email or user_email.
  3. Check that you are passing the correct value inside identifiers - make sure that this matches the user that you’re trying to track, and matches the key and embeddable ID that you’re using.
  4. Check that you are formatting identifiers correctly - the value must be a stringified JSON value. E.g. for email addresses, the value must be "\"test@test.com\"" (note the double quotes). This can become double-escaped (e.g. "\\"test@test.com\\"") in certain code environments.
  5. Check that the user has definitely provided their unique identifier before the track event is triggered - trying to track a user based on an email address that hasn’t been captured yet is impossible.