Webhooks

Get notified when an interview completes. Configure a webhook URL and we’ll POST a signed payload with interview results every time a respondent finishes.

`PUT /v1/webhooks`

Create or update the webhook configuration for your project. One webhook per project. Returns the webhook configuration. On first creation, includes the signing_secret.

Request

string

required

Bearer token. See Authentication.

string

required

HTTPS endpoint to receive events.

string[]

required

Event types to subscribe to. Currently: ["interview.completed"].

curl -X PUT https://app.userjourneys.ai/api/v1/webhooks \
  -H "Authorization: Bearer uj_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/userjourneys",
    "events": ["interview.completed"]
  }'

const response = await fetch(
  "https://app.userjourneys.ai/api/v1/webhooks",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer uj_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://your-app.com/webhooks/userjourneys",
      events: ["interview.completed"],
    }),
  }
);
const data = await response.json();
// data.signing_secret — save this, only shown once

import requests

response = requests.put(
    "https://app.userjourneys.ai/api/v1/webhooks",
    headers={"Authorization": "Bearer uj_live_your_key_here"},
    json={
        "url": "https://your-app.com/webhooks/userjourneys",
        "events": ["interview.completed"],
    },
)
data = response.json()
# data["signing_secret"] — save this, only shown once

{
  "url": "https://your-app.com/webhooks/userjourneys",
  "events": ["interview.completed"],
  "signing_secret": "whsec_5b69ff6a12af94c6e3901a061180ca73"
}

{
  "url": "https://your-app.com/webhooks/userjourneys",
  "events": ["interview.completed"]
}

The signing_secret is only returned on first creation (201). Store it securely — you’ll need it to verify payloads. Lost or need to rotate your secret? Delete the webhook and create a new one. Deletion only requires your API key.

`GET /v1/webhooks`

Retrieve the current webhook configuration. Returns the URL and subscribed events. Does not return the signing secret.

curl https://app.userjourneys.ai/api/v1/webhooks \
  -H "Authorization: Bearer uj_live_your_key_here"

Returns 404 if no webhook is configured.

`DELETE /v1/webhooks`

Remove the webhook configuration.

curl -X DELETE https://app.userjourneys.ai/api/v1/webhooks \
  -H "Authorization: Bearer uj_live_your_key_here"

Returns 204 on success.

Event: `interview.completed`

Sent after interview processing completes, typically 5–30 seconds after the respondent finishes.

Headers

Header	Value
`Content-Type`	`application/json`
`X-Webhook-Event`	`interview.completed`
`X-Webhook-Signature`	HMAC-SHA256 signature of the request body

Payload

string

"interview.completed"

string

ISO 8601 timestamp of when the event was sent.

object

Show properties

string

Interview ID (UUID). Use this with GET /v1/interviews/:id to fetch the full transcript.

string | null

Study this interview belongs to. Matches the id in GET /v1/studies.

string | null

Study display name.

string

Deprecated alias for interview_id. Use interview_id instead.

string | null

Deprecated alias for study_id. Use study_id instead.

string | null

Deprecated alias for study_name. Use study_name instead.

string | null

Public interview URL for this experiment.

string

"completed"

string

Interview start time (ISO 8601).

string | null

Interview end time (ISO 8601).

integer | null

Interview length in seconds.

string | null

"insightful", "successful", or "unsuccessful".

string | null

Detected language code (e.g. "en", "es", "de").

string | null

Custom identifier passed via the ?reference_id= query parameter on the interview link. Use this to match completions back to users in your system.

string | null

Email entered during or after the interview. null if not collected.

string | null

Respondent ID, if triggered via a respondent-specific link.

{
  "event": "interview.completed",
  "timestamp": "2026-03-11T14:32:00.123Z",
  "data": {
    "interview_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
    "study_name": "Onboarding Feedback",
    "session_id": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "experiment_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
    "experiment_name": "Onboarding Feedback",
    "interview_link": "https://app.userjourneys.ai/i/xK9mR2pQ",
    "status": "completed",
    "started_at": "2026-03-11T14:20:00.000Z",
    "completed_at": "2026-03-11T14:30:00.456Z",
    "duration_secs": 580,
    "quality_score": "insightful",
    "language": "en",
    "reference_id": "user_12345",
    "respondent_email": null,
    "respondent_id": null
  }
}

Retries

If your endpoint returns a non-2xx status or times out (10s limit), we retry up to 3 times:

Attempt	Delay
1st retry	10 seconds
2nd retry	1 minute
3rd retry	5 minutes

After all retries are exhausted, the event is dropped.

Use session_id to deduplicate in case you receive the same event more than once.

Verifying signatures

Every webhook includes an X-Webhook-Signature header. Verify it to confirm the request came from userjourneys.ai.

Node.js

import crypto from "node:crypto";

function verifyWebhookSignature(body, signature, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express example
app.post("/webhooks/userjourneys", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const isValid = verifyWebhookSignature(req.body, signature, SIGNING_SECRET);

  if (isValid === false) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  // Handle the event...

  res.status(200).send("OK");
});

Python

import hashlib
import hmac

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route("/webhooks/userjourneys", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Webhook-Signature")
    is_valid = verify_webhook_signature(
        request.data, signature, SIGNING_SECRET
    )

    if not is_valid:
        return "Invalid signature", 401

    event = request.get_json()
    # Handle the event...

    return "OK", 200

Use timing-safe comparison (crypto.timingSafeEqual, hmac.compare_digest) to prevent timing attacks.

Typical integration

Mark users after they complete an interview so you stop showing the prompt:

app.post("/webhooks/userjourneys", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  if (verifyWebhookSignature(req.body, signature, SIGNING_SECRET) === false) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = JSON.parse(req.body);

  if (event === "interview.completed" && data.reference_id) {
    await db.users.update({
      where: { id: data.reference_id },
      data: { interview_completed: true },
    });
  }

  res.status(200).send("OK");
});

Getting Started

Interviews

React Native SDK

Integrations

AI Agent

Guides

API

Support

`PUT /v1/webhooks`

Request

`GET /v1/webhooks`

`DELETE /v1/webhooks`

Event: `interview.completed`

Headers

Payload

Retries

Verifying signatures

Typical integration

​PUT /v1/webhooks

​Request

​GET /v1/webhooks

​DELETE /v1/webhooks

​Event: interview.completed

​Headers

​Payload

​Retries

​Verifying signatures

​Typical integration

`PUT /v1/webhooks`

Request

`GET /v1/webhooks`

`DELETE /v1/webhooks`

Event: `interview.completed`

Headers

Payload

Retries

Verifying signatures

Typical integration