Webhooks
Webhooks allow you to get programmatic notifications or automated messages from CORE about changes to your data as they happen.
Rather than requiring you to pull information via our API, webhooks allow you to push information to your endpoint. You can choose which events you should be notified about by subscribing to them. When a subscribed event is triggered (say a new project is added), CORE sends it as an HTTP POST request with a JSON body to the endpoint you specify.
Adding Webhook Event Subscriptions
You can add webhook event subscriptions to your application via your CORE Developer account.
- Log in to your Developer Portal account and go to the Dashboard.
- Click the Webhooks button next to your application.
- In the Edit Webhooks dialog, check the Enable Webhooks toggle and enter the Endpoint URL where you want to receive the events.
- Select the Action (e.g., Create, Update, Delete, etc.) for each Entity (e.g., Account, Activity, Invoice, etc.) that should trigger webhook events.
- Click Save.
You are now subscribed to the webhook events represented by the Entity-Action combination, and when any of the actions occur for an entity, the events are sent to the endpoint URL.
An endpoint URL is the HTTP endpoint where your preferred events are sent. CORE can send them only to a full, valid, and publicly accessible URL.
After enabling webhooks, a CORE company must connect to your app by granting a new access token. This is important to start receiving webhooks for that company. If you are a CORE customer using our APIs, you need to trigger this via your app by requesting an access token and granting permission. If you are a developer whose app is meant for CORE users, the connection is created whenever a CORE user grants permission to your app on the consent dialog.
Events in CORE
Events are our way of letting you know when something important happens to your data. You can select what kind of events you want to receive and which ones you don't. The modules (entities) in CORE can support the following event types (actions):
| Event Type | Description |
|---|---|
Create | Occurs when a new object is created |
Update | Occurs when an existing object is updated |
Delete | Occurs when an object is deleted |
Void | Occurs when an object is voided |
Workflow | Occurs when an object undergoes a workflow action, i.e., the object is submitted, approved, rejected, etc. |
The Void event is only available for the Invoice and Payment objects, and the Workflow event is only available for the TimeEntry object.
Webhooks JSON Format
Webhook events are sent as HTTP POST requests with a JSON body. The JSON body has a standard format and includes metadata, EventId as well as actual data that has changed in the event (Payload). It contains the following fields:
| Field | Description |
|---|---|
Id | Identifier of the entity or object on which the event has occurred |
CompanyId | Identifier of the CORE company where the event has occurred |
UserId | Identifier of the CORE userThe identifier is linked to the user’s login and is different from the identifier of the employee or vendor linked to the user. who triggered the webhook event |
Timestamp | The date and time of the event in Epoch time format |
EventId | Unique identifier of the event |
Event | The type of the event, e.g., “invoice.delete” |
Payload | The full JSON object associated with the event |
Type | Type of the Payload, e.g., “Invoice” |
For example, if an event is triggered on the deletion of an invoice, the following JSON may be sent in its body:
For Delete and Void events, the payload is empty and for Workflow events, the payload contains the WorkFlowState object.
Retry Logic and Status Codes
CORE expects a range of status codes or messages in response to the webhook events it sends. If the delivery of the events is not successful for some reason, CORE attempts a finite number of retries in some cases. A total of 5 attempts are made with an interval of 30 seconds between each retry.
A 2XX status code range indicates a successful delivery of the webhook event to the endpoint URL.
A 4XX status code indicates the endpoint did not accept the event for some reason. So no further attempts (or retries) are made to send the event as the response is not expected to change. Exceptions to this are the 408 (Request Timeout) and 429 (Too Many Requests) status codes, because here the response is expected to change.
A 5XX status code indicates a server error, usually on the user’s end. CORE treats such responses as a failure and attempts retries.
Validating Webhook Events
To make sure the webhook events you receive are authentic and not tampered with, CORE sends a signature in the form of the X-BQECore-Signature header in the HTTP POST request of the event. This signature header is a base64 encoded string computed using the SHA-256 hashing algorithm and contains the hash of the payload concatenated with the hash of the Client Secret of your app. If your app does not have a Client Secret, it uses the Client ID. Using the Payload in computing the hash ensures that you can verify it has not been tampered with, while using the client key ensures the event is coming from CORE. The signature is computed as:
X-BQECore-Signature = base64 (SHA-256 (SHA-256 (Payload) + SHA-256 (Client Secret or Client ID) ) )
You can compute the above signature at your end using the Payload you receive in the event and the Client Secret or Client ID of your application. If it matches the signature you received in the X-BQECore-Signature header, you can be sure of the authenticity of the event.
Best Practices
When using webhooks in CORE, we recommend that you follow these best practices in order to make the most of this feature.
- Listen for limited event types: You should configure your webhook endpoint to receive only those types of events that are required by your integration. Listening for extra events (or all events) puts undue strain on your server and is not recommended. You can change the events that are sent to a webhook endpoint in the CORE Developer account dashboard.
- Delivery attempts and retry logic: When webhook events are not acknowledged by your endpoint within a stipulated time, CORE makes a finite number of retry attempts for them in some cases as discussed in the Retry Logic and Status Codes section. So you must configure your endpoint to handle the retries.
- Event handling: Handling webhook events correctly is crucial to making sure that the business logic of your integration works as expected.
- Duplicate events: Webhook endpoints can sometimes receive the same event more than once. You can handle duplicate receipts by making your event processing idempotent. One way of doing this is logging the events you have processed and then not processing already-logged events. As each event contains a unique EventId, it is easy to identify duplicates.
- Order of events: CORE does not guarantee delivery of events in the order in which they are generated. For example, creating an invoice also updates the associated time entries, and it may generate events in the following order:
invoice.create
time entry.update (multiple events if there are multiple time entries)
Your endpoint should not expect delivery of these events in this order and should handle this accordingly.
- Security: Keeping your endpoints secure is critical to protecting your clients’ information. There are several ways to make sure the events are coming from CORE in a secure manner.
- X-BQECore-Signature header: CORE sends an X-BQECore-Signature header in the HTTP POST request of the events. We strongly recommend that you validate the events you receive using this header as discussed in the Validating Webhook Events section.
- Receiving events with an HTTPS server: If you use an HTTPS URL for your webhook endpoint, CORE validates that the connection to your server is secure before sending you webhook events. For this to work, you must configure your server to support HTTPS, with a valid server certificate.