evenbooks
Sign inStart for free

Webhooks

Get notified when something changes.

Paths are relative to https://evenbooks.org/api/v1. How keys, errors, paging and versions work is in the guide; the whole reference is also an OpenAPI 3.1 document.

Administrator key marks endpoints that need a key with the admin role, Write access those a read-only key can’t call, and Idempotent those that accept an idempotency key.

Resend a delivery

post/webhook-deliveries/{id}/retry
Administrator keyWrite access

Sends the same event again right away, also after it failed for good.

Parameters

  • idstring (uuid)path · required

Response 200

WebhookDeliveryDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

List webhook endpoints

get/webhook-endpoints
Administrator key

Response 200

Errors 400 · 401 · 403 · 404 · 409 · 429

Add a webhook endpoint

post/webhook-endpoints
Administrator keyWrite access

Subscribes an https URL to events (an empty events list means every event type). The signing secret is in the response and is never shown again.

Request body

CreateWebhookEndpointInput

  • urlstringrequired

    1–2000 characters

  • descriptionstring or null

    up to 200 characters

  • eventsarray of string · WebhookEventType
    47 possible values

    invoice.draft_created invoice.issued invoice.paid invoice.voided invoice.email_sent invoice.email_failed invoice.deleted credit_note.issued credit_note.applied credit_note.voided credit_note.deleted payment.created payment.allocated payment.allocation_reversed payment.voided payment.deleted refund.created refund.voided refund.deleted purchase.created purchase.voided purchase.deleted journal.posted journal.reversed journal_entry.deleted bank_transaction.created bank_transaction.categorized bank_transaction.matched bank_transaction.transfer bank_transaction.excluded bank_transaction.review_undone bank_transaction.deleted bank_connection.synced bank_connection.sync_failed import.committed contact.created contact.updated contact.archived item.created item.updated recurring.issued reconciliation.completed period.closed period.reopened processor.charge_settled processor.dispute_opened processor.payout_posted

    up to 47 items · default []

Response 200

WebhookEndpointWithSecretDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get a webhook endpoint

get/webhook-endpoints/{id}
Administrator key

Parameters

  • idstring (uuid)path · required

Response 200

WebhookEndpointDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Change a webhook endpoint

patch/webhook-endpoints/{id}
Administrator keyWrite access

Omitted fields stay as they are. enabled: false turns the endpoint off and drops its pending deliveries; enabled: true turns it back on.

Parameters

  • idstring (uuid)path · required

Request body

UpdateWebhookEndpointInput

  • urlstring

    1–2000 characters

  • descriptionstring or null

    up to 200 characters

  • eventsarray of string · WebhookEventType
    47 possible values

    invoice.draft_created invoice.issued invoice.paid invoice.voided invoice.email_sent invoice.email_failed invoice.deleted credit_note.issued credit_note.applied credit_note.voided credit_note.deleted payment.created payment.allocated payment.allocation_reversed payment.voided payment.deleted refund.created refund.voided refund.deleted purchase.created purchase.voided purchase.deleted journal.posted journal.reversed journal_entry.deleted bank_transaction.created bank_transaction.categorized bank_transaction.matched bank_transaction.transfer bank_transaction.excluded bank_transaction.review_undone bank_transaction.deleted bank_connection.synced bank_connection.sync_failed import.committed contact.created contact.updated contact.archived item.created item.updated recurring.issued reconciliation.completed period.closed period.reopened processor.charge_settled processor.dispute_opened processor.payout_posted

    up to 47 items

  • enabledboolean

Response 200

WebhookEndpointDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Delete a webhook endpoint

delete/webhook-endpoints/{id}
Administrator keyWrite access

Also deletes its delivery log.

Parameters

  • idstring (uuid)path · required

Response 200

DeleteWebhookEndpointsIdResponse

  • deletedboolean

    Always true

Errors 400 · 401 · 403 · 404 · 409 · 429

List deliveries to an endpoint

get/webhook-endpoints/{id}/deliveries
Administrator key

Newest first. Kept for 30 days.

Parameters

  • idstring (uuid)path · required
  • limitintegerquery

    1–100 · default 25

  • cursorstringquery

    up to 200 characters

  • statusstring · WebhookDeliveryStatusquery

    One of: pending succeeded failed

Response 200

A page of WebhookDeliveryDto ({ items, nextCursor, total }, see paging).

Errors 400 · 401 · 403 · 404 · 409 · 429

Rotate a webhook signing secret

post/webhook-endpoints/{id}/rotate-secret
Administrator keyWrite access

The old secret stops working at once. The new one is in the response and is never shown again.

Parameters

  • idstring (uuid)path · required

Response 200

WebhookEndpointWithSecretDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Send a test event

post/webhook-endpoints/{id}/test
Administrator keyWrite access

Sends a ping event to the endpoint right away and returns the delivery, including the status code your server answered with.

Parameters

  • idstring (uuid)path · required

Response 200

WebhookDeliveryDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Schemas

The types these endpoints take or return, by name. Type names above link here.

Uuid

string (uuid)

WebhookDeliveryDto

  • idstring · Uuid
  • endpointIdstring · Uuid
  • eventIdstring · Uuid
  • eventTypestring
  • entityTypestring
  • entityIdstring or null
  • statusstring · WebhookDeliveryStatus

    One of: pending succeeded failed

  • attemptsinteger
  • nextAttemptAtstring or null
  • lastAttemptAtstring or null
  • lastStatusCodeinteger or null
  • lastErrorstring or null
  • lastResponsestring or null
  • deliveredAtstring or null
  • createdAtstring

WebhookDeliveryStatus

string

One of: pending succeeded failed

WebhookEndpointDto

  • idstring · Uuid
  • urlstring
  • descriptionstring or null
  • eventsarray of string
  • statusstring · WebhookEndpointStatus

    One of: enabled disabled

  • disabledReasonstring or null

    One of: user failing key_revoked

  • secretPrefixstring
  • failingSincestring or null
  • lastSuccessAtstring or null
  • lastFailureAtstring or null
  • createdBystring
  • configuredByApiKeyobject or null
    Show 2 fields
    • idstring · Uuid
    • namestring
  • createdAtstring
  • updatedAtstring

WebhookEndpointStatus

string

One of: enabled disabled

WebhookEndpointWithSecretDto

WebhookEventType

string

47 possible values

invoice.draft_created invoice.issued invoice.paid invoice.voided invoice.email_sent invoice.email_failed invoice.deleted credit_note.issued credit_note.applied credit_note.voided credit_note.deleted payment.created payment.allocated payment.allocation_reversed payment.voided payment.deleted refund.created refund.voided refund.deleted purchase.created purchase.voided purchase.deleted journal.posted journal.reversed journal_entry.deleted bank_transaction.created bank_transaction.categorized bank_transaction.matched bank_transaction.transfer bank_transaction.excluded bank_transaction.review_undone bank_transaction.deleted bank_connection.synced bank_connection.sync_failed import.committed contact.created contact.updated contact.archived item.created item.updated recurring.issued reconciliation.completed period.closed period.reopened processor.charge_settled processor.dispute_opened processor.payout_posted