---
title: "HTTP Deployment Handler"
description: "Effortlessly deploy packages to custom HTTP endpoints using Cloud CMS for database synchronization and CDN logic integration. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/engine/deployment/deployment-handlers/http"
---

# HTTP Deployment Handler

Handles the deployment of one or more Deployment Packages to a custom HTTP endpoint.

The custom HTTP endpoint is described by:

- `url`
- `statusUrl`
- `username`
- `password`

Custom HTTP endpoints are useful for a large variety of purposes, including writing data into custom databases, synchronizing content from Cloud CMS with existing Content Management products, hooking into custom logic for CDN or cache invalidation and much more.

## Configuration

```
{
    "url": "{url}",
    "statusUrl": "{statusUrl}",
    "username": "{username}",
    "password": "{password}"
}
```

Where `url` is the remote address of the server and `username` and `password` describe the credentials to be applied using Basic Authentication. The `statusUrl` is optional - it enables Cloud CMS to poll your endpoint for completion.

## How it works

The remote HTTP endpoint must be a POST handler. All POSTs to the endpoint will be `multipart/form-data` and will contain the following parts:

```
package
archive-{guid1}
archive-{guid2}
...
```

There will be at least 2 parts (`package` and `archive-{guid1}`) where `guid1` is the ID of the archive that contains the JSON and binaries being deployed. A deployment package may also have multiple archives in which case there will be more parts. Your custom HTTP endpoint should consider the prefixes of the incoming parts to determine how each is applicable.

The `package` part provides the JSON for the deployment package.

The HTTP endpoint should acknowledge receipt of the deployment package by returning a 200 and a JSON payload that contains an ID for the deployment package on the endpoint. It may look like this:

```
{
    "_doc": "{remoteDeploymentPackageId}"
}
```

This `_doc`, for all intents and purposes, serves as a job ID or a task ID for the background processing that is now occurring against the deployment package on the remote HTTP server.

The `statusUrl` property is optional. If it is provided, Cloud CMS will poll the HTTP endpoint using the aforementioned `_doc` to check on the status of the deployment package.

If you do choose to provide `statusUrl`, then it should point to a `GET` method that returns the deployment package JSON. This JSON should more or less look like this:

```
{
    "_doc": "",
    "state": "PENDING|PROCESSING|SUCCESS|ERROR",
    "operation": "DEPLOY|UNDEPLOY",
    "retain": true|false,
    "records": [{
        "_doc": "",
        "state": "NONE|DIRTY|PROCESSING|FINISHED|ERROR",
        "operation": "DEPLOY|UNDEPLOY",
        "ref": "",
        "success": true|false,
        "message": ""
    }, ...]
}
```

The `state` of the deployment package indicates whether the HTTP endpoint has finished processing all of the records contained within it. When it finishes, it should either flip to `SUCCESS` or `ERROR`. Further, each individual deployment record should have its state adjusted to `FINISHED` or `ERROR`. Further, the `success` field should be tripped to either `true` or `false`. Any deployment records that fail should have their `message` set so that meaningful information can be conveyed back to Cloud CMS about what went wrong.

The `statusUrl` value is allowed to use a special `id` field to fill in the `_doc` of the deployment record as acquired from the initial push. You can populate this using handlebars, like this:

[http://deployer.mywebsite.com/status/{{id}}](http://deployer.mywebsite.com/status/%7B%7Bid%7D%7D "http://deployer.mywebsite.com/status/{{id}}")

Or:

[http://deployer.mywebsite.com/status?id={{id}}](http://deployer.mywebsite.com/status?id=%7B%7Bid%7D%7D "http://deployer.mywebsite.com/status?id={{id}}")

## Example Configuration

```
{
    "url": "http://deployer.mywebsite.com/push",
    "statusUrl": "http://deployer.mywebsite.com/status/"
    "username": "inigo",
    "password": "montoya"
}
```

## Building your own HTTP Deployment Receiver

We encourage you to go on and build some really cool and interesting Cloud CMS Deployment Receivers. To help you get started, we provide a Node.js-based custom HTTP Deployment Receiver that shows off what is possible. It is available in our SDK, here:

[https://github.com/gitana/sdk/tree/master/http-deployment-receiver](https://github.com/gitana/sdk/tree/master/http-deployment-receiver "https://github.com/gitana/sdk/tree/master/http-deployment-receiver")

To configure this within your own Cloud CMS environment, just add an `http` Deployment Target and configure it a bit like this:

![config.png](/documentation/gitana/4.0/engine/deployment/deployment-handlers/http/config.png)

This Custom HTTP Deployment Receiver uses a small library which is available here:

[https://github.com/gitana/cloudcms-http-deployment-receiver](https://github.com/gitana/cloudcms-http-deployment-receiver "https://github.com/gitana/cloudcms-http-deployment-receiver")

We encourage you to take a closer look at this library. It may give you a head start in terms of building out your own custom HTTP Deployment Receivers. At the very least, it should serve as a useful technical reference to compare your own implementations against.

When testing your receiver, you need to ensure that the endpoint is accessible to the outside world, or at the least accessible to the API. On premise users using the API in a docker container hosted on a Mac or Windows PC can access receiver services hosted on the same machine by using the `host.docker.internal` address. So, for example, when creating your deployment receiver in cloudcms to connect to a local server bound to port 3000, you would configure to the url parameter as `http://host.docker.internal:3000`.