When building FlatPeak integrations, you might want your applications to receive events as they occur in your FlatPeak account.

When an event occurs (for example when a Customer object is created), FlatPeak generates a new Event object. By registering webhook endpoints in your FlatPeak account, you enable FlatPeak to automatically send Event objects as part of POST requests to the registered webhook endpoint hosted by your application. After your webhook endpoint receives the Event, your app can run backend actions.

Receiving webhook events is particularly useful for listening to asynchronous events, such as when a customer’s contract with their energy provider expires.

​
Event object

The Event object we send to your webhook endpoint provides a snapshot of the object that changed or has been created:

{
  "id": "evt_65e42b7827c0526548432b9f",
  "object": "event",
  "time_created": "2022-01-24T14:15:22Z",
  "type": "device.create",
  "data": {
    "id": "dev_63a6087272941ef077a8fd3e",
    "object": "device",
    "account_id": "acc_661677911f2197045e6cf1b1",
    "live_mode": true,
    "reference_id": "DEV1234567890",
    "last_seen": "2022-01-24T14:15:22Z",
    "time_created": "2022-01-24T14:15:22Z"
  }
}

A full list of FlatPeak event types is available in the events guide.

​
Pending deliveries

Use webhook logs in the Dashboard to determine how many endpoints haven’t responded successfully to delivery. You can expedite resending or force failed deliveries to try again from there. FlatPeak will automatically retry deliveries on the following schedule:

TimeDescription
ImmediatelyAs soon as an event has occurred
30 secondsIn 30 seconds if the first delivery attempt is unsuccessful.
1 hourIn 30 seconds if the first delivery attempt is unsuccessful.
6 hoursIn 30 seconds if the first delivery attempt is unsuccessful.
12 hoursIn 30 seconds if the first delivery attempt is unsuccessful.
24 hoursIn 24 hours. If this delivery attempt is unsuccessful, there will be no more automatic retries. Go to the Webhooks in the Dashboard to initiate the redelivery of failed webhooks.

​
Delivery timeouts

FlatPeak will wait up to 10 seconds for your server to respond to the delivery attempt, after which the attempt will be deemed failed if no response from your server has been received.

​
Delivery queue

​
Debugging webhook integrations

Multiple types of issues can occur when delivering events to your webhook endpoint:

  • FlatPeak might not be able to deliver an event to your webhook endpoint.
  • Your webhook endpoint might have an SSL issue.
  • Your network connectivity is intermittent.
  • Your webhook endpoint isn’t receiving events that you expect to receive.

​
HTTP status codes

When an event displays a status code of 200, it indicates successful delivery to the webhook endpoint. You might also receive a status code other than 200. View the table below for a list of common HTTP status codes and recommended solutions.

Webhook statusDescriptionFix.
(Unable to connect) ERRWe’re unable to establish a connection to the destination server.Make sure that your host domain is publicly accessible to the internet.
(302) ERR (or another 3xx status)The destination server attempted to redirect the request to another location. We consider redirect responses to webhook requests as failures.Set the webhook endpoint destination to the URL resolved by the redirect.
(400) ERR (or other 4xx status)The destination server can’t or won’t process the request. This might occur when the server detects an error (400) when the destination URL has access restrictions, (401, 403), or when the destination URL doesn’t exist (404).Make sure that your endpoint is publicly accessible to the internet and make sure that your endpoint accepts a POST HTTP method.
(500) ERR (or other 5xx status)The destination server encountered an error while processing the request.Review your application’s logs to understand why it’s returning a 500 error.
(TLS error) ERRWe couldn’t establish a secure connection to the destination server. These errors are usually caused by an issue with the SSL/TLS certificate or an intermediate certificate in the destination server’s certificate chain.Perform an SSL server test to find issues that might cause this error.
(Timed out) ERRThe destination server took too long to respond to the webhook request.Make sure you defer complex logic and return a successful response immediately in your webhook handling code.

Was this page helpful?

PaginationObjects deletion