Webhooks Intro

Webhook events will be sent over HTTPS to endpoints configured in "My Company" -> "PayKeeper API".

Authentication

You can verify that PayKeeper is the one sending you webhook events by validating the "Authorization" HTTP header. The header value will be "Basic <auth_string>". To verify auth_string, decode using base64. The resulting string will be “[organization_id]:[webhook_secret]”. Your webhook secret is available on your organization's PayKeeper API page.

Topics

Event Structure

HTTP requests will be made to configured endpoints utilizing HTTP Headers and request Body. Data will be sent in JSON and will include the topic, event information, and link to associated structure.

Event Data Structure

Events sent from PayKeeper will be in JSON and will include the topic, projectId, data and link, which will include a link to the updated information.

{
  "topic": "project.funding.changed",
  "projectId": "0920f13b-b426-4b2b-97d9-45ab3e5f6eff",
  "data": {
    "projectId": "0920f13b-b426-4b2b-97d9-45ab3e5f6eff",
    "amountPending": -2000,
    "amount": 2000
  },
  "link": "https://app-dev.paykeeper.com/api/public/projects/0920f13b-b426-4b2b-97d9-45ab3e5f6eff/funding"
}

Schemas by topic

project.changed

• projectId - id of the affected project
• previousContractAmount - Contract amount of the project prior to this change event
• contractAmount - Contract amount of the project after this change event

project.funding.changed

• projectId - id of the affected project
• amountPending - changed amount of pending project funds. Can be negative
• amount - changed amount of posted project funds. Can be negative

project.schedule.changed

• projectId - id of the affected project
• milestone
  • id - id of the changed milestone
  • name - name of the changed milestone
• step - Project schedule milestone step changed

project.disbursements.changed

• projectId - id of the affected project
• disbursementId - id of the disbursement
• referenceCode - reference code of the disbursement
• amount - amount of the disbursement
• organization
  • id - id of the organization the disbursement was made to
  • name - name of the organization the disbursement was made to

project.active-status.changed

• projectId - id of the affected project
• status - updated status of the project. ("CANCELLED", "UNCANCELLED", "SETTLED")

Retries

• If your endpoint takes longer than 5 seconds to respond, we will time out and retry the request
• Events associated with HTTP status codes 409, 429, and 5xx are retried.
• Events associated with HTTP status codes 1xx, 2xx, 3xx, and 4xx (excluding 409 & 429) are not retried.
• Timeouts or non-success response codes will result in us retrying delivery with an exponential backoff, with a maximum of 185 tries over the first 24 hours.