API: set up and operate webhooks

Webhooks send edoobox events to your integration’s technical receiving address. There you can, for example, retrieve an updated booking in the CRM. Webhook management uses the API resource /v2/webhook. This guide is intended for developers responsible for integration.

Prepare role, API access and receiving address

Setup requires API access with webhook write permission; reading back additionally requires read permission. A read-only key cannot create a new webhook configuration. The prepared Zapier permission includes webhook management; the WordPress permission permits only reading here. For a custom integration, use an appropriately restricted permission group and check its other permissions.

Prepare a permanently reachable HTTPS address on your own server, such as https://example.org/integrationen/edoobox.
Generate your own random webhook secret and store it securely at the receiver. This secret is separate from the API key secret.
Create or check API access under API keys and access permissions.
Authenticate according to API: First steps using the correct host, bearer token and edid.
Check required resource permissions and your integration’s availability in the account. Enabled API access alone does not define the substantive scope of any arbitrary connection.

Do not confuse general API setup with a payment provider webhook or scanner receiving address. Such connections have their own specialist guides and credentials.

Create the webhook as inactive first

Send POST /v2/webhook with Content-Type: application/json and your usual Authorization and edid headers. The following body is an example; replace receiving address and secret with your own values.

{
  "data": {
    "status": false,
    "url": "https://example.org/integrationen/edoobox",
    "secret": "EIGENES_ZUFAELLIGES_WEBHOOK_SECRET",
    "topics": ["post_Booking", "put_Booking"]
  }
}

Check HTTP status and error in the response and save the returned public webhook ID. Use the same ID for later changes; if results are unclear, do not create a second entry without checking. First read GET /v2/webhook/list.

Field	Use
`status`	`false` for preparation, `true` to receive matching events.
`url`	Your server’s technical receiving address.
`secret`	Shared secret for the HMAC signature. Keep it secure; do not treat the returned value as a complete backup.
`topics`	List of desired event names.
`basicauth`	Optional additional HTTP Basic Auth credentials for the receiver. Use only if its setup is coordinated accordingly.

Complete field descriptions and HTTP operations are provided in the API v2 reference.

Choose topics deliberately and read them back

For bookings, post_Booking and put_Booking are established examples. They represent creation and modification in corresponding booking processes. Do not invent a topic name from a specific business status such as ‘paid’. Check the actual required business event with a suitable demo booking.

Read configuration back using GET /v2/webhook/{id} and compare URL, status and saved topics. Unknown or misspelled entries may be ignored on saving; a successful response alone does not confirm adoption of every desired name.

Updating the topics list sets the complete desired list. An empty list removes saved topics. Therefore also send event names still required.

Check receipt and signature against the unchanged body

edoobox sends an HTTP POST with JSON. The edhook header identifies the specific transmission. If a secret is stored, edsignature contains a hexadecimal HMAC-SHA256 signature of the sent JSON body. Calculate the comparison from unchanged received bytes. Parsing and reserialising JSON first may alter order or character encoding.

import { createHmac, timingSafeEqual } from 'node:crypto';

function validEdooboxSignature(rawBody, signature, secret) {
  if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/i.test(signature)) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}
// Preserve rawBody as an unchanged Buffer before running a JSON parser.
// Read secret from protected server storage.

First check signature and assignment to the configured connection. Then process JSON content. It contains a hook section with, among other things, topic, time, method, account and webhook, plus a data section. Data shape depends on event and generation route; an extension may contain additional data.

The context value hook.edid is not an API access token. For a subsequent REST request, continue to use your own successful API authentication and its account context.

Activate and check the entire process

Read the prepared configuration back and check receiver, secret configuration and topics.
Activate it with PUT /v2/webhook/{id} and body {"data":{"status":true}}.
In an agreed demo process, trigger an appropriate new booking or booking change.
At the receiver, check actual HTTP POST, topic, signature, data shape and booking ID.
Retrieve the affected resource using your own API access and check the update in the destination system.
Also check repeat processing of the same booking and a temporarily unavailable receiver.

The sender waits only briefly for the receiving response. Therefore first store a checked event durably in your own queue and respond promptly with HTTP 200. Your background service then handles longer CRM tasks. A receipt acknowledgement should be given only once your system can reliably resume accepted work.

Handle repeated events and missing delivery

Use edhook, topic and resource ID for traceable processing. Prevent duplicate bookings or CRM actions even when the same resource change arrives by different routes. Your destination system’s processing state belongs in its durable storage.

Do not assume exactly-once delivery, a fixed order or guaranteed retry intervals. Check the actual receipt log and compare the current edoobox record. The supplementary REST booking reconciliation covers later cancellations, deduplication and processing state completed only after a full run.

For missing messages, check active status, stored topics, action actually performed, receiving address, firewall, signature validation and receiver log. An API GET of a booking does not itself generate a creation or change event. Do not create actual duplicate bookings for troubleshooting.

Change address, secret or operation in a controlled way

If needed, disable configuration using PUT /v2/webhook/{id} and {"data":{"status":false}}. Read status back afterwards. Disabling does not remove work already accepted by the receiver from its queue.

Change URL, secret and topics using the same ID. Coordinate a secret change between sender configuration and receiver and check the signature before reactivation. To permanently remove an entry, DELETE /v2/webhook/{id} supports deletion. Check dependencies beforehand and retain REST reconciliation as a controlled transition.

Example: Adopt a booking change in the CRM

An organisation operates its own booking receiver. After a valid signature, it stores the message and acknowledges receipt. The background service determines the affected booking, reads its current edoobox state and updates the stored CRM mapping. Another event for the same booking updates the same record.

A regular REST run additionally reconciles relevant bookings. This makes temporary receiving disruptions manageable. The example assumes a custom integration; creating a webhook does not create a finished CRM reconciliation.