Webhook

View as Markdown

Webhook

A webhook sends data to a URL that you choose when an event happens in a stack. It keeps a third-party app or service in sync with your content. The Webhook class builds the Content Management API requests that manage the webhooks of one stack. Use this class to

  • list, read, create, update, delete and export webhooks
  • read the executions and execution logs of a webhook
  • retry a failed execution

Call the webhook method of the Stack class to get an instance.

addHeader

addHeader adds one header to every request that this Webhook object builds.

NameTypeDescription
key (required)String

Names the header.

Default: Not applicable
value (required)String

Sets the header value.

Default: Not applicable

Returns: Webhook. The same webhook, for chaining.

Validation

  • There is no client-side validation. addHeader stores any name and value.
  • A null name or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Client-side only. addHeader stores the header on this object and sends no request.
  • Every request method of Webhook sends the header, together with the headers that the object copied from the stack, such as api_key and authorization.
  • A second call with the same name replaces the value. A name that matches a stack header, such as branch, replaces that header for this object.
  • The header stays on this object only. The stack and other objects keep their own headers. importWebhook also stores a Content-Type header on this object.

Example

Basic usage: send an extra header with each request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AddWebhookHeader {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");
        webhook.addHeader("X-Request-Id", "read-webhook-01");

        Response<ResponseBody> response = webhook.fetch().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addHeaders

addHeaders adds every entry of a map as a header of the requests that this Webhook object builds.

NameTypeDescription
headers (required)HashMap<String, String>

Maps each header name to its value.

Default: Not applicable

Returns: Webhook. The same webhook, for chaining.

Validation

  • Throws NullPointerException if the map is null, because addHeaders copies its entries.
  • A null name or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Client-side only. addHeaders copies the entries into the headers of this object and sends no request.
  • A name that already exists takes the new value. Headers that the map does not name stay as they are.
  • Every request method of Webhook sends the headers.
  • The header stays on this object only. The stack and other objects keep their own headers. importWebhook also stores a Content-Type header on this object.
  • The addHeader method adds one header at a time.

Example

Basic usage: send two extra headers with each request

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AddWebhookHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");
        HashMap<String, String> headers = new HashMap<>();
        headers.put("X-Request-Id", "read-webhook-01");
        headers.put("X-Client-Name", "webhook-audit");
        webhook.addHeaders(headers);

        Response<ResponseBody> response = webhook.fetch().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParam

addParam adds one query parameter to this Webhook object, for the requests that send query parameters.

NameTypeDescription
key (required)String

Names the query parameter.

Default: Not applicable
value (required)Object

Sets the parameter value, sent as its string form.

Default: Not applicable

Returns: Webhook. The same webhook, for chaining.

Validation

  • There is no client-side validation. addParam stores any key and value.
  • A null key or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Client-side only. addParam stores the pair on this object and sends no request.
  • Only the following requests send the stored parameters: find and getExecutions.
  • fetch, create, update, delete, export, importWebhook, importExisting, retry and getExecutionLog send no query parameters, so a value you add has no effect on them.
  • Retrofit writes each value with its toString() form, so pass a String, a Boolean or a number.
  • A second call with the same key replaces the value.
  • The parameter stays on this object for every later request until removeParam removes it.

Example

Basic usage: limit the executions of a webhook to a date range

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class AddWebhookParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");
        webhook.addParam("from", "2026-11-01T00:00:00.000Z");
        webhook.addParam("to", "2026-11-13T23:59:59.999Z");

        Response<ResponseBody> response = webhook.getExecutions().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParams

addParams adds every entry of a map as a query parameter of this Webhook object.

NameTypeDescription
params (required)HashMap<String, Object>

Maps each query parameter name to its value.

Default: Not applicable

Returns: Webhook. The same webhook, for chaining.

Validation

  • Throws NullPointerException if the map is null, because addParams copies its entries.
  • A null key or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Client-side only. addParams copies the entries into the parameters of this object and sends no request.
  • A key that already exists takes the new value. Parameters that the map does not name stay as they are.
  • Only the following requests send the stored parameters: find and getExecutions.
  • The addParam method adds one parameter at a time.

Example

Basic usage: filter the executions of a webhook by date and leave out request details

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.util.HashMap;

public class AddWebhookParams {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");
        HashMap<String, Object> query = new HashMap<>();
        query.put("from", "2026-11-01T00:00:00.000Z");
        query.put("to", "2026-11-13T23:59:59.999Z");
        query.put("only_events", true);
        webhook.addParams(query);

        Response<ResponseBody> response = webhook.getExecutions().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

create

create creates a webhook in the stack from the details in the request body.

NameTypeDescription
requestBody (required)JSONObject

Holds the webhook details under a webhook key.

Default: Not applicable
requestBody.webhook.name (required)String

Names the webhook.

Default: Not applicable
requestBody.webhook.destinations (required)Array

Lists the target URLs, authentication details and custom headers.

Default: Not applicable
requestBody.webhook.channels (required)Array

Lists the events that trigger the webhook.

Default: Not applicable
requestBody.webhook.branches (required)Array

Lists the branches the webhook covers.

Default: Not applicable
requestBody.webhook.disabledBoolean

Disables the webhook when true.

Default: API default
requestBody.webhook.concise_payloadBoolean

Sends a concise payload when true.

Default: API default

Returns: Call<ResponseBody>. The request that creates the webhook, sent when you call execute().

Validation

  • There is no client-side validation. create sends the body unchanged.
  • A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/webhooks with the body as JSON, as Create a webhook describes.
  • disabled set to false enables the webhook, and true disables it.
  • concise_payload set to true sends a concise JSON payload to the target URL. false sends the full payload.
  • Sends no query parameters. create ignores the UID of the instance.

Example

Basic usage: create a webhook for entry publish events

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class CreateWebhook {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();

        JSONObject destination = new JSONObject();
        destination.put("target_url", "https://example.com/hooks/contentstack");
        JSONArray destinations = new JSONArray();
        destinations.add(destination);
        JSONArray channels = new JSONArray();
        channels.add("content_types.entries.publish.success");
        JSONArray branches = new JSONArray();
        branches.add("main");

        JSONObject details = new JSONObject();
        details.put("name", "docs-test-publish-hook");
        details.put("destinations", destinations);
        details.put("channels", channels);
        details.put("branches", branches);
        details.put("disabled", false);
        details.put("concise_payload", true);
        JSONObject body = new JSONObject();
        body.put("webhook", details);

        Response<ResponseBody> response = webhook.create(body).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

delete

delete deletes the webhook whose UID you passed to stack.webhook(webhookUid).

Returns: Call<ResponseBody>. The request that deletes the webhook, sent when you call execute().

Validation

  • Throws IllegalAccessError if the instance has no webhook UID, or an empty one, because delete removes one webhook. Get the instance with stack.webhook(webhookUid).
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends DELETE /v3/webhooks/{webhook_uid}, as Delete webhook describes.
  • Sends no query parameters. Values from addParam do not reach this request.

Example

Basic usage: delete one webhook

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class DeleteWebhook {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");

        Response<ResponseBody> response = webhook.delete().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

export

export exports the settings of the webhook whose UID you passed to stack.webhook(webhookUid) as JSON.

Returns: Call<ResponseBody>. The request for the exported webhook, sent when you call execute().

Validation

  • Throws IllegalAccessError if the instance has no webhook UID, or an empty one, because export exports one webhook. Get the instance with stack.webhook(webhookUid).
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/webhooks/{webhook_uid}/export, as Export a Webhook describes.
  • Sends no query parameters. Values from addParam do not reach this request.
  • The response body holds the webhook data as JSON. The SDK saves no file, so write response.body().string() to a file yourself.

Example

Basic usage: save a webhook as a JSON file

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

public class ExportWebhook {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");

        Response<ResponseBody> response = webhook.export().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        Files.write(Paths.get("<FILE_PATH>"), response.body().string().getBytes(StandardCharsets.UTF_8));
    }
}

fetch

fetch retrieves the webhook whose UID you passed to stack.webhook(webhookUid).

Returns: Call<ResponseBody>. The request for the webhook, sent when you call execute().

Validation

  • Throws IllegalAccessError if the instance has no webhook UID, or an empty one, because fetch reads one webhook. Get the instance with stack.webhook(webhookUid).
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/webhooks/{webhook_uid}, as Get webhook describes.
  • Sends no query parameters. Values from addParam do not reach this request.
  • The response body is the raw JSON of the API, with the webhook under its webhook key.

Example

Basic usage: read one webhook

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FetchWebhook {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");

        Response<ResponseBody> response = webhook.fetch().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Edge case: call fetch on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;

public class FetchWebhookWithoutUid {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();

        try {
            webhook.fetch();
        } catch (IllegalAccessError e) {
            // Thrown before any request, because the instance holds no webhook UID
            System.out.println("No webhook UID: " + e.getMessage());
        }
    }
}

find

find lists the webhooks of the stack.

Returns: Call<ResponseBody>. The request for all webhooks in the stack, sent when you call execute().

Validation

  • There is no client-side validation.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/webhooks with every query parameter stored on this object, as Get all webhooks describes.
  • The API reference lists no query parameters for this request.
  • find ignores the UID of the instance. The response body is the raw JSON of the API, with the webhooks in its webhooks array.

Example

Basic usage: list the webhooks of a stack

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class FindWebhooks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();

        Response<ResponseBody> response = webhook.find().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

getExecutionLog

getExecutionLog retrieves the latest log of one webhook execution.

NameTypeDescription
executionUid (required)String

Identifies the execution whose log to read.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the execution log, sent when you call execute().

Validation

  • There is no client-side validation. A null execution UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/webhooks/{execution_uid}/logs, as Get latest execution log of a webhook describes.
  • The path takes the execution UID, not the webhook UID. Read it from the response of getExecutions.
  • getExecutionLog ignores the UID of the instance, and sends no query parameters.

Example

Basic usage: read the log of one execution

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class GetWebhookExecutionLog {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();
        // The execution UID, from the response of getExecutions
        String executionUid = args[0];

        Response<ResponseBody> response = webhook.getExecutionLog(executionUid).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

getExecutions

getExecutions lists the executions of the webhook whose UID you passed to stack.webhook(webhookUid).

Returns: Call<ResponseBody>. The request for the executions of the webhook, sent when you call execute().

Validation

  • Throws IllegalAccessError if the instance has no webhook UID, or an empty one, because getExecutions reads the executions of one webhook. Get the instance with stack.webhook(webhookUid).
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/webhooks/{webhook_uid}/executions with every query parameter stored on this object, as Get executions of a webhook describes.
  • Add query parameters with addParam first. The API accepts the following four:
    • from and to: limit the executions to a date range, each an ISO date such as 2026-11-01T00:00:00.000Z.
    • query: a JSON query on status, for example {"status":{"$gte":"400","$lte":"599"}} for failed executions.
    • only_events: set to true to leave out the request details of each execution.
  • The API returns execution data for the last 30 days only.
  • Each execution carries an execution UID. Pass it to retry or getExecutionLog.

Example

Basic usage: list the executions of a webhook

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class GetWebhookExecutions {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");

        Response<ResponseBody> response = webhook.getExecutions().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

Query parameters: list successful executions in a date range

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class GetSuccessfulExecutions {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>")
                .addParam("from", "2026-11-01T00:00:00.000Z")
                .addParam("to", "2026-11-13T23:59:59.999Z")
                .addParam("query", "{\"status\":{\"$gte\":\"200\",\"$lte\":\"399\"}}")
                .addParam("only_events", true);

        Response<ResponseBody> response = webhook.getExecutions().execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

Edge case: call getExecutions on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;

public class GetExecutionsWithoutUid {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();

        try {
            webhook.getExecutions();
        } catch (IllegalAccessError e) {
            // Thrown before any request, because the instance holds no webhook UID
            System.out.println("No webhook UID: " + e.getMessage());
        }
    }
}

importExisting

importExisting builds a POST request to the webhook import path, with no file and no webhook UID.

Returns: Call<ResponseBody>. The request to the webhook import path, sent when you call execute().

Validation

  • There is no client-side validation, and importExisting does not throw.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/webhooks/import with the headers of this object, an empty body and no query parameters.
  • importExisting ignores the UID of the instance.

Example

Basic usage: update an existing webhook with update instead

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;

public class UpdateInsteadOfImport {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");

        JSONObject details = new JSONObject();
        details.put("name", "docs-test-publish-hook-v2");
        JSONObject body = new JSONObject();
        body.put("webhook", details);

        Response<ResponseBody> response = webhook.update(body).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

importWebhook

importWebhook is meant to build a request that imports a new webhook from a JSON file.

NameTypeDescription
fileName (required)String

Names the uploaded file in the form data.

Default: Not applicable
jsonPath (required)String

Gives the path of the webhook JSON file.

Default: Not applicable

Returns: Call<ResponseBody>. The request that imports the webhook file, sent when you call execute().

Validation

  • Throws IllegalArgumentException for every input, because Retrofit rejects the request definition that importWebhook uses. No request leaves the client.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Before it throws, importWebhook adds a Content-Type: multipart/form-data header to this object. The header stays, so later requests from the same object send it too. Call importWebhook on a separate instance.
  • importWebhook puts the jsonPath text itself in the form data. It does not read the file at that path.

Example

Edge case: catch the exception that importWebhook throws

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;

public class ImportWebhookFile {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        // A separate instance, because importWebhook leaves a Content-Type header on it
        Webhook importer = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();

        try {
            importer.importWebhook("webhook.json", "<FILE_PATH>");
        } catch (IllegalArgumentException e) {
            // Thrown on every call, before any request
            System.out.println("Import not available in the SDK: " + e.getMessage());
        }
    }
}

removeParam

removeParam removes one query parameter from this Webhook object.

NameTypeDescription
key (required)String

Names the query parameter to remove.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • There is no client-side validation. A key that the object does not hold, or a null key, changes nothing.
  • The change applies to the next request that sends query parameters, and an invalid remaining value surfaces as an API error when you call execute() on it.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Client-side only. removeParam deletes the key from the parameters of this object and sends no request.
  • Later calls to find and getExecutions no longer send the parameter.
  • removeParam returns void, so it does not chain. Call it as its own statement.
  • The object keeps every other parameter and every header.

Example

Basic usage: drop the end date from the execution filter

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class RemoveWebhookParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");
        webhook.addParam("from", "2026-11-01T00:00:00.000Z").addParam("to", "2026-11-13T23:59:59.999Z");
        // Later requests send from only
        webhook.removeParam("to");

        Response<ResponseBody> response = webhook.getExecutions().execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

retry

retry asks the API to run one webhook execution again, after the webhook has finished its automatic attempts.

NameTypeDescription
executionUid (required)String

Identifies the execution to run again.

Default: Not applicable

Returns: Call<ResponseBody>. The request that retries the execution, sent when you call execute().

Validation

  • There is no client-side validation. A null execution UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/webhooks/{execution_uid}/retry, as Retry a webhook describes.
  • The path takes the execution UID, not the webhook UID. Read it from the response of getExecutions.
  • retry ignores the UID of the instance, and sends no query parameters.

Example

Basic usage: retry one execution

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class RetryWebhookExecution {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook();
        // The execution UID, from the response of getExecutions
        String executionUid = args[0];

        Response<ResponseBody> response = webhook.retry(executionUid).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

update

update changes the details of the webhook whose UID you passed to stack.webhook(webhookUid).

NameTypeDescription
requestBody (required)JSONObject

Holds the webhook details under a webhook key.

Default: Not applicable
requestBody.webhook.nameString

Names the webhook.

Default: API default
requestBody.webhook.destinationsArray

Lists the target URLs, authentication details and custom headers.

Default: API default
requestBody.webhook.channelsArray

Lists the events that trigger the webhook.

Default: API default
requestBody.webhook.branchesArray

Lists the branches the webhook covers.

Default: API default
requestBody.webhook.disabledBoolean

Disables the webhook when true.

Default: API default
requestBody.webhook.concise_payloadBoolean

Sends a concise payload when true.

Default: API default

Returns: Call<ResponseBody>. The request that updates the webhook, sent when you call execute().

Validation

  • Throws IllegalAccessError if the instance has no webhook UID, or an empty one, because update changes one webhook. Get the instance with stack.webhook(webhookUid).
  • A null body makes execute() throw IllegalArgumentException, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends PUT /v3/webhooks/{webhook_uid} with the body as JSON, as Update webhook describes.
  • Set disabled to true to pause the webhook without deleting it.
  • Sends no query parameters. Values from addParam do not reach this request.

Example

Basic usage: disable a webhook

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Webhook;
import org.json.simple.JSONObject;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class DisableWebhook {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Webhook webhook = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").webhook("<WEBHOOK_UID>");

        JSONObject details = new JSONObject();
        details.put("disabled", true);
        JSONObject body = new JSONObject();
        body.put("webhook", details);

        Response<ResponseBody> response = webhook.update(body).execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}