Receiving Webhooks

In order to receive webhooks from the Church Online Platform your server will need to meet some some base requirements outlined below.

Secure Transport

We require and verify that the endpoint is secured with a valid SSL certificate over HTTPS.

Content Type

All events will be sent via a POST request with a Content-Type of application/json .

Event Payload

All webhook event payloads will follow the CloudEvents Spec. The following example shows a CloudEvent serialized as JSON:

{
    "specversion" : "1.0",
    "type" : "church.online.user.created",
    "source" : "https://live.example.church",
    "id" : "16e8d84c-282e-48e2-9114-6ce02b5c2104",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/json",
    "dataschema": "https://developers.online.church/docs/cloudevents/spec/user",
    "data" : {
      "key": "value"
    }
}

specversion
The CloudEvent spec version of the event.

type
A value describing the type of event relating to the occurrence.

source
The context in which the event happened. This will usually be a URI reference to your church online experience.

id
Identifies the event. If an event is received with the same value for id it can be assumed to be a duplicate.

time
A timestamp indicating when this request was made. This is not the timestamp of when the actual event occurred; that will be indicated in the event data payload.

datacontenttype
The content type of the data attribute. In the context of webhooks, this value will always be application/json.

dataschema
A URI reference to documentation of the event schema.

data
The payload of the event. Most events contain a few common fields inside data: primarily user and service, which are documented here. Other fields are specific to the event, such as totalTimeAttended.

Ordering of Events

The Church Online Platform does not guarantee delivery of events in the order in which they occur. Your endpoint should not expect delivery of events in order and handle this accordingly.

Responding

Success

If the webhook was successfully accepted your server should respond with a 200 OK, 201 Created or 202 Accepted status code to indicate success.

Failure

All status codes outside the 2xx range will be considered a failure. The response must not use any of the 3xx Redirect status codes.

If your server is unable to process a request due to exceeding a request rate limit, it should return a 429 Too Many Requests status code and must include a Retry-After header. The value of the Retry-After header can be either an HTTP-date or a number of milliseconds to delay after the response is received. We will observe the value of the header and refrain from sending further requests until the indicated time.

We will retry failures with an exponential backoff. This will result in 25 retries attempted over approximately 21 days. Because of this, it is important that your servers processing of requests be idempotent. On retries, we will include two additional headers:

• X-Chop-Webhook-Retry - An integer value of the number of retry attempts
• X-Chop-Webhook-Identifier - A unique identifier of the event being sent

After the last attempted retry, we will consider the event a failure and move it to a dead job queue. A list of failed events will be shown on the Webhook configuration screen in the Admin.