NewsCred

Webhooks

Webhooks allow you to subscribe to certain events on NewsCred to get programmatical notifications. When one of those events happen, we’ll send a HTTP POST payload with a JSON body to the configured callback URL.

Registering webhooks

To register a webhook, you will need to provide the following information

Supported events

asset_added

When an asset (article, image, video or raw file) is added to Library. An asset may be added to Library for several reasons including, but not limited to, uploading assets, completing a task, etc.

Payload

Key Type Description
event_name string Name of the event. For this event, the value is asset_added.
data object Data of the event.
data[asset] object Data of the asset associated with the event.
data[asset][id] string Unique identifier of the asset.
data[asset][type] string Type of the asset. Value can be article, image, video or raw_file.
data[asset][links] object Links related to the asset
data[asset][links][self] string URL to fetch the asset’s details through NewsCred Open API.

Example

{
    "event_name": "asset_added",
    "data": {
        "asset": {
            "id": "019a86405de737b4ec3e616a4aeff981",
            "type": "image",
            "links": {
                "self": "https://api.newscred.com/v3/images/019a86405de737b4ec3e616a4aeff981"
            }
        }
    }
}

asset_removed

When an asset (article, image, video or raw file) is removed from Library. An asset may be removed from Library for several reasons including, but not limited to, deleting assets.

Payload

Key Type Description
event_name string Name of the event. For this event, the value is asset_removed.
data object Data of the event.
data[asset] object Data of the asset associated with the event.
data[asset][id] string Unique identifier of the asset.
data[asset][type] string Type of the asset. Value can be article, image, video or raw_file.

Example

{
    "event_name": "asset_removed",
    "data": {
        "asset": {
            "id": "870825113a12950a7eeeb64a64236d49",
            "type": "article"
        }
    }
}

asset_modified

When an asset (article, image, video or raw file) is modified in Library. Currently this event will be triggered only for the modification of the asset’s labels (both standard and custom).

Payload

Key Type Description
event_name string Name of the event. For this event, the value is asset_modified.
data object Data of the event.
data[asset] object Data of the asset associated with the event.
data[asset][id] string Unique identifier of the asset.
data[asset][type] string Type of the asset. Value can be article, image, video or raw_file.
data[asset][links] object Links related to the asset
data[asset][links][self] string URL to fetch the asset’s details through NewsCred Open API.

Example

{
    "event_name": "asset_modified",
    "data": {
        "asset": {
            "id": "019a86405de737b4ec3e616a4aeff951",
            "type": "image",
            "links": {
                "self": "https://api.newscred.com/v3/images/019a86405de737b4ec3e616a4aeff951"
            }
        }
    }
}

external_sub_step_started

When an external sub step is started from a task.

Payload

Key Type Description
event_name string Name of the event. For this event, the value is external_sub_step_started.
data object Data of the event.
data[task] object Data of the task associated with the external sub step.
data[task][id] string Unique identifier of the task.
data[task][links] object Links related to the task
data[task][links][self] string URL to fetch task’s details through NewsCred Open API.
data[task][links][assets] string URL to fetch assets’ details used in the task through NewsCred Open API.
data[step] object Data of the step associated with the external sub step.
data[step][id] string Unique identifier of the step.
data[step][links][task] string URL to fetch task’s details associated with the step through NewsCred Open API.
data[sub_step] object Data of the sub step associated with the external sub step.
data[sub_step][id] string Unique identifier of the sub step.
data[sub_step][links][self] string URL to fetch sub step’s details through NewsCred Open API.
data[sub_step][links][task] string URL to fetch task’s details associated with the sub step through NewsCred Open API.
data[sub_step][links][external_work] string URL to fetch external work’s details associated with the sub step through NewsCred Open API.
data[external_work] object Data of the external work associated with the external sub step.
data[external_work][external_system] string Name of the external system associated with the external work.
data[external_work][links][self] string URL to fetch external work’s details through NewsCred Open API.
data[external_work][links][task] string URL to fetch task’s details associated with the external work through NewsCred Open API.
data[external_work][links][sub_step] string URL to fetch sub step’s details associated with the external work through NewsCred Open API.

Example

{
    "event_name": "external_sub_step_started",
    "data": {
        "task": {
            "id": "5f6a0312a5963d0591015e3e",
            "links": {
                "self": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e",
                "assets": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e/assets"
            }
        },
        "step": {
            "id": "5f68911d83eeb10591933b49",
            "links": {
                "task": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e"
            }
        },
        "sub_step": {
            "id": "5f68911d83eeb10591933b4a",
            "links": {
                "self": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e/steps/5f68911d83eeb10591933b49/sub-steps/5f68911d83eeb10591933b4a",
                "task": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e",
                "external_work": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e/steps/5f68911d83eeb10591933b49/sub-steps/5f68911d83eeb10591933b4a/external-work"
            }
        },
        "external_work": {
            "external_system": "Trello",
            "links": {
                "self": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e/steps/5f68911d83eeb10591933b49/sub-steps/5f68911d83eeb10591933b4a/external-work",
                "task": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e",
                "sub_step": "https://api.newscred.com/v3/tasks/5f6a0312a5963d0591015e3e/steps/5f68911d83eeb10591933b49/sub-steps/5f68911d83eeb10591933b4a"
            }
        }
    }
}

Security

You can provide a secret (random string up to 32 character) while registering a webhook. If provided, we will send the secret with the HTTP POST request in the Callback-Secret header when triggering the webhook event.

When you receive the event in your callback URL, you can validate the secret from the Callback-Secret header.

Event delivery

Acknowledgement

When you receive an event, acknowledge the delivery by returning an HTTP 200 or 202 status code. Anything other than 200 or 202 will be considered as delivery failure.

Timeout

It is expected that the callback endpoint will respond within 10 seconds of receiving the webhook event. If it takes more then 10 seconds, the connection will be terminated and will be considered as delivery failure.

Retry

In case of delivery failure, NewsCred will retry to deliver the event for up to three days with an exponential back off.

Duplicate events

In rare cases, callback endpoints might receive the same event more than once. Please make your event processing idempotent to guard against duplicated events.

Delivery sequence

NewsCred does not guarantee the delivery of events in the sequence in which they are generated. You can always use the NewsCred Open API to fetch the latest data.

Backward compatibility

The following changes are considered to be backward compatible: