Skip to main content

Creating the webhook

Node.js Users​

Consider using our Node.js SDK.

Others​

TestBox requests trials from you by sending a POST request to a URL you specify. We will send the POST request with the following JSON payload:

{
    "version": "1",
    "trial_id": "<UUID>",
    "success_url": "https://example.com",
    "failure_url": "https://example.com"
}

Once the request is made, you may respond in one of two ways: synchronously or asynchronously. Regardless of how you respond, the payload response is the same, which is covered here.

Response Payload​

{
    "start_url_context": {},
    "secret_context": {},
    "admin_authentication": {},
    "trial_users": [],
    "created_at": "2022-05-05 12:34:56"
}

We'll cover each section below.

start_url_context​

If you have a subdomain, or any other fixed information about the account that is required in the URL to access the account, it belongs in start_url_context. For example, suppose you segment your accounts by subdomain:

https://my-account-name.zappyproduct.com/

In this case, your start_url_context might be:

{
    "subdomain": "my-account-name"
}

In the broader context...

{
    "start_url_context": {
        "subdomain": "my-account-name"
    }
}

There is no schema on start_url_context, only that it is a dictionary of values.

secret_context​

info

This field is only relevant if you are using JWT SSO

Any secrets that are relevant to your trial account will live in secret_context. Currently there is only one secret that we allow: sso_jwt_secret.

{
    "sso_jwt_secret": "a-long-string-that-will-be-used-to-sign-jwt-tokens-for-jwt-sso"
}

admin_authentication​

The "admin authentication" object is used to describe the "original user." This user would be the equivalent of a user who actually signed up for your product from your web site. It also allows you to pass us an API token. This API token is used to ingest sample data into your product.

{
    "user": {
        "email": "something@example.com",
        "password": "a-password-which-is-required-if-you-use-client-side-login",
        "totp_token": "the-totp-key-if-you-use-client-side-login-and-require-totp",
    },
    "api_token": "if-the-admin-user-has-an-api-key-put-it-here"
}

trial_users​

Most products demo best if they have multiple users associated with a single account. That way, you can demonstrate any multi-user features your product offers. Work with your Partner Success Manager to determine the right number of users to create. Once you've created them, you can pass them to us in an array of TrialUser objects. A TrialUser looks like this:

{
    "email": "my-name@example.com",
    "password": "a-password-which-is-required-if-you-use-client-side-login",
    "totp_token": "the-totp-key-if-you-use-client-side-login-and-require-totp"
}

Synchronously​

If you are able to make your trials quickly and easily, a synchronous response is best. You must respond with a 201 Created HTTP status code, with the body of the response as outlined above.

Asynchronosuly​

If you require some amount of processing time to create an account, you may choose to reply to our systems later with an asynchronous reply.

First, tell our systems that you will respond later by responding to our webhook request with a 200 OK response. Anything else is considered a failure.

When ready, make a POST HTTP request to the URL provided in the success_url key of the webhook request. The body of this request should match the payload schema. provided above.

Reporting Failures​

You can optionally report failures directly to TestBox to make errors display in your Partner Portal. To report an error, make a POST request to the failure_url specified in our webhook request. There is no schema for error reporting, but it is expected to be a JSON payload. We will display the payload back to you in the portal to help diagnose issues.

Of course, error reporting is optional. Eventually, asynchronous trials will time out and display as an error.