Webhooks

11 min

Webhooks enable notifications about content publishing events. Configure webhooks as custom properties on publications to receive HTTP callbacks when content is published or updated.

Quick Start

Here is a minimal configuration to get started:

{
  "processOnce": false,
  "filter": {
    "type": "POST",
    "properties": []
  },
  "notification": {
    "url": "https://your-endpoint.com/webhook",
    "method": "POST",
    "parameters": {
      "id": "{{id}}",
      "preview": "{{preview}}"
    }
  }
}

This configuration will send a webhook notification to your endpoint whenever POST content in the publication is published or updated.

When Webhooks Trigger

Webhooks are triggered in the following scenarios:

When content is published for the first time

When already-published content is saved/updated (unless processOnce is set to true)

When content is republished

When the publication date is reached for scheduled content (if sendPublicationDateReachedNotifications is enabled, release mode only)

Webhooks are not triggered when:

Content status changes (e.g., from draft to review)

Content is created but not published

Content is deleted

Webhook Configuration

Settings are applied as custom properties on the Publication using the key webhook_config.

Example configuration:

{
  "processOnce": true,
  "sendPublicationDateReachedNotifications": false,
  "filter": {
    "type": "POST",
    "properties": [
      {
        "key": "print.transfer",
        "value": "true"
      }
    ]
  },
  "notification": {
    "url": "https://your-endpoint.com/webhook",
    "method": "POST",
    "headers": {
      "X-Api-Key": "your-api-key"
    },
    "parameters": {
      "id": "{{id}}",
      "preview": "{{preview}}",
      "publicationDate": "{{publicationDate}}",
      "scheduled": "{{scheduled}}"
    }
  }
}

Property	Type	Required	Default	Description
processOnce	Boolean	No	true	If set to true, the webhook will only be triggered on the first publish event. Subsequent updates to already-published content will not trigger the webhook.
sendPublicationDateReachedNotifications	Boolean	No	false	If set to true, webhooks will be triggered when the publication date is reached for scheduled content. This notification is only sent for release mode, not preview mode.
filter	ContentFilter	Yes	-	Specifies which content should trigger the webhook.
notification	NotificationConfig	Yes	-	Specifies how the webhook notification should be sent.

ContentFilter

Property	Type	Required	Description
type	String	Yes	The type of content that should trigger the webhook. Possible values: ISSUE, POST, BUNDLE
properties	Array	No	An array of custom property filters. Only content that has all specified properties with the specified values will trigger the webhook. If the array is empty, all content of the specified type will trigger the webhook.

Properties

Each property filter has the following structure:

Property	Type	Description
key	String	The property key
value	String	The property value

NotificationConfig

Property	Type	Required	Description
url	String	Yes	The URL to send the webhook notification to
method	String	Yes	The HTTP method to use for the webhook request. Possible values: GET, POST
headers	Map<String,String>	No	Custom headers to include in the webhook request (e.g., API keys, authorization headers)
parameters	Map<String,String>	No	Parameters to include in the webhook request. Values can use template variables (see below)

Parameters & Variables

Parameters support dynamic values using template variables. Variables are wrapped in double curly braces: {{variableName}}.

The following variables are available:

Variable	Description
{{id}}	The content ID
{{name}}	The content name
{{postType}}	The post type (only for POST content)
{{preview}}	Boolean indicating if this is preview mode (true) or release mode (false)
{{externalId}}	The external ID
{{publicationDate}}	The publication date in ISO 8601 UTC format (e.g., 2024-03-15T14:30:00Z)
{{scheduled}}	Boolean indicating if the publication date is in the future (true) or not (false). This parameter is automatically excluded when preview=true.
{{property.your-property-key}}	The value of a custom property with the key your-property-key

When using the GET method, parameters are sent as query parameters in the URL:

https://your-endpoint.com/webhook?id=123&preview=false

When using the POST method, parameters are sent as JSON in the request body:

{
  "id": "123",
  "preview": "false"
}

Testing

Before deploying to production, test your webhook configuration using services like webhook.site, requestbin.com, or hookbin.com.

These services provide temporary URLs that capture and display incoming webhook requests, allowing you to verify the payload and headers.

Testing workflow:

Create a temporary webhook URL using a testing service

Configure your publication with the test webhook URL

Publish or update content that matches your filter

Check the testing service to verify the webhook was received

Verify the parameters and headers are correct

Update configuration with your production endpoint

Troubleshooting

If your webhook is not being triggered, check the following:

Required fields: Ensure all required fields are present in the configuration (filter, notification, url, method, type)

Content type: Verify that the content type matches the filter configuration

Property filters: If using property filters, ensure the content has all specified properties with the correct values

JSON syntax: Validate your JSON configuration using a JSON validator

Trigger conditions: Ensure the content is being published (not just saved as draft) and that processOnce is not preventing subsequent triggers

Limitations

No retry when the webhook endpoint is temporarily unavailable (i.e., due to a network error)

Webhook requests timeout after 20 seconds