Submit a configured event

Submit an existing public event name with a value and optional application data. The HTTP result describes completion of the Wallkit submission path; it does not certify queue acceptance or downstream handling.

Task	Operation
Submit a public configured event	Submit event

Example clients and synthetic values follow response conventions.

Submit an event

POST /api/v1/user/event

Submit an event for the resolved resource and optional member. Wallkit validates the name against its configured public event list, builds request context and attempts to send a queue message. This is not an inbound webhook receiver or an outbound webhook delivery contract.

Before you call

A valid resource is required; guest submission is permitted. A member token is optional and selects identity through the existing session context. There is no active-member requirement in this event initializer. Existing configured Firebase handling can affect identity; see credential transport.

Obtain an existing public event name from the integration owner. Validation uses a cached global list of Events whose private flag is false, without a resource filter; it does not establish which downstream handler exists for this resource. No complete event-name enum or cache lifetime is supplied here.

Request

Send a JSON object.

Name	Location	Type / requirement	Meaning / constraints
resource	header	resource public key; required	Selects the resolved resource.
token	header	optional member session token	Selects the resolved member, when present; not required for guest submission.
name	JSON	nonempty string; required	Lowercased and stripped of tags; must match a configured public event name.
value	JSON	nonempty string; required	Lowercased and stripped of tags. Use text; no Boolean or numeric value schema is established.
data	JSON	optional application object	Nested custom data, object-cast; defaults to an empty object. No event-specific nested schema or field allowlist is enforced here.
content_key	JSON	optional nonempty string	Trimmed content reference; this action does not validate article existence or grant access.
custom_recipient_email	JSON	optional nonempty string	Email-filtered, lowercased and trimmed; no dedicated email-validity check or delivery guarantee.

Top-level user_id, resource_id and session_id are not caller selectors. Wallkit supplies resolved identity/session and request IP, user-agent, referrer, host and language. Nested data does not override those top-level values. Queue processing adds an event timestamp. Omit unrelated top-level fields; they are not forwarded by this action.

Result

HTTP 200 with the following field:

Field	Type / presence	Meaning
result	Boolean true	Submission path returned. It is not a queue acknowledgment, event-handler outcome or delivery receipt.

The queue helper catches send failures, and the event wrapper discards its result. No message ID is returned. A repeat request attempts another send; no deduplication, ordering, retry or delivery contract is established. Other initialization failures may still surface without an action-specific error shape.

Example: Submit a guest preference event

Assume the integration owner has already configured the synthetic public name example_preference_saved. It is not a built-in event name. This request deliberately omits a member token, so it does not select a Wallkit member by a body ID.

curl -X POST "${WALLKIT_API_BASE}/api/v1/user/event" \
  -H "resource: ${RESOURCE_KEY}" \
  -H "Content-Type: application/json" \
  --data-raw '{"name": "example_preference_saved", "value": "enabled", "data": {"source": "example preference form"}}'

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/user/event`, {
  method: "POST", headers: { "resource": process.env.RESOURCE_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({"name": "example_preference_saved", "value": "enabled", "data": {"source": "example preference form"}})
});
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

body = {'name': 'example_preference_saved', 'value': 'enabled', 'data': {'source': 'example preference form'}}
request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/user/event",
    data=json.dumps(body).encode("utf-8"), headers={"resource": os.environ["RESOURCE_KEY"], "Content-Type": "application/json"}, method="POST")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

Synthetic HTTP 200 excerpt:

{
  "result": true
}

The application can record that the submission path returned. It cannot infer that a downstream subscription, email or membership change happened.

Consequential alternate

For an unknown or unavailable public name, a synthetic HTTP 409 response is:

{
  "error": "invalid_event_name",
  "error_description": "Event with this name not found",
  "req_guid": "example-request"
}

Change the name only after checking the owner-supplied configuration. A public-list lookup failure can produce the same response; do not invent a replacement event name.

Recovery

HTTP status	Code / shape	Cause	Next action
409	invalid_event_name / The event name is required	Missing/empty name.	Send the owner-supplied public event name.
409	invalid_event_name / Event with this name not found	Name absent from public cached list, or lookup failed.	Confirm the configured public name and selected integration with the owner.
409	invalid_event_value / The event value is required	Missing/empty value.	Send meaningful nonempty text for this configured event.
404	resource_not_exists / Incorrect resource key	Invalid resolved resource.	Check the resource public key; changing the event name will not repair it.
200	result:true without a receipt	Send failure can be caught inside the queue helper.	Use separate application/owner evidence for downstream effects; do not blindly repeat, since duplication is possible.

Send valid JSON. Missing or malformed input can reach name validation; do not depend on a universal 406 malformed-body response for this action.

Next task

Choose the next operation according to the application’s actual job. For provider preferences, read Mailchimp interests; for article delivery, use the separate content-access walkthrough. Neither follows automatically from an event response.

Follow the task guide

Read the Event tickets: submit a configured event for request order, context choices and response decisions.