Webhook API (PUSH)

Set up your webhook

1. Provide ChurchDesk with the HTTPS URL that should receive webhook actions. Contact support@churchdesk.com to arrange access.
2. ChurchDesk sends an HTTP POSTrequest to that URL when a subscribed event is created, updated or deleted.
3. Return HTTP 200 OKpromptly to acknowledge the action.
4. Use the action-specific partnerTokenand resource link to retrieve the affected event.

1. Actions

Actions tell partners when something interesting happens in a subscribed church. For example, when an event is updated, ChurchDesk creates an action.event.updateaction and posts it to your webhook URL.

1.1 Attributes

id integer

The action identifier.

object string

Identifies the payload as an action.

createdAt string

The creation date and time in ISO 8601 UTC format.

partnerToken string

A token unique to this action. It cannot be reused to fetch a different entity.

type string

One of action.event.create, action.event.updateor action.event.delete.

data object

Information about the affected entity: its id, object type and resource links.

1.2 Example

When a subscribed church creates an event, ChurchDesk sends a payload like this:

{
  "id": "36471834",
  "object": "action",
  "createdAt": "2015-11-15T09:30:00.000Z",
  "partnerToken": "uniqueToken",
  "data": {
    "object": "event",
    "id": "123",
    "links": {
      "self": "https://api.churchdesk.com/events/123?partnerToken=uniqueToken"
    }
  },
  "type": "action.event.create"
}

The event retrieval operation and its request schema are available in the Partnership endpoint reference.

1.3 Responding to a webhook

Return HTTP 200 OKto acknowledge receipt. Any other status, including a redirect, is treated as a failed delivery.

If delivery fails, ChurchDesk retries once an hour for up to three days.

1.4 Best practices

Acknowledge the webhook before performing slow processing or network calls. Queue the work and return 200 OK immediately so ChurchDesk does not retry a successfully received action.

2. Partner categories

A partner can provide a JSON endpoint containing categories that ChurchDesk users may associate with ChurchDesk categories or resources.

2.1 Attributes

partnerName string

The name shown to ChurchDesk users.

machineName string

The short partner identifier included in resources such as events.

partnerLink string

A link where customers can find more information about the partner.

categories object[]

The partner categories available for selection.

2.2 Example

{
  "partnerName": "Automated Heating Inc.",
  "machineName": "AHI",
  "partnerLink": "https://partner.example.com",
  "categories": [
    { "id": "temp-2", "name": "Very hot (24 Celsius)" },
    { "id": "temp-4", "name": "Medium temperature" },
    { "id": "temp-6", "name": "Low temperature" }
  ]
}

When a ChurchDesk category or resource is associated with a partner category, events include it under targetPartnerCategories:

{
  "categories": [
    {
      "id": 2,
      "name": "Concerts",
      "targetPartnerCategories": [
        { "machineName": "AHI", "id": "temp-4" }
      ]
    }
  ]
}