A pattern that has worked well for GitHub Apps is to treat webhooks as the event source and the GitHub API as the source for additional/current data, rather than polling the API continuously.

A typical architecture would look something like:

GitHub → Webhook endpoint → Validate → Persist/Queue event → Worker → GitHub API → Your DB

1. Use the webhook payload first

I would process as much as possible from the webhook payload itself. Webhook payloads often contain the repository, installation, sender, PR/issue information, action, etc.

If the payload already contains everything required for the operation, there is no reason to make another API request.

For example, if I receive a pull_request.opened event and only need the PR number, repository, author and title, I can use the webhook payload directly.

I'd make an API request when I need information that isn't included in the payload, need a more complete representation, or need to verify/fetch the latest state.

This also helps avoid unnecessary API/rate-limit usage. GitHub itself recommends webhooks over polling when you need to monitor many resources.

2. Make webhook processing idempotent

I wouldn't assume webhook delivery is exactly-once or ordered.

GitHub documents that webhook deliveries can arrive out of order, and delivery can also be delayed.

I'd therefore store the delivery ID (X-GitHub-Delivery) or an equivalent event identifier and make processing idempotent.

For example:

Receive event
    ↓
Validate signature
    ↓
Check delivery ID
    ↓
Already processed? → Yes → return 2xx
    ↓ No
Persist event
    ↓
Queue job
    ↓
Return 2xx quickly

The worker can then safely retry a job without accidentally performing the same operation twice.

3. Don't do heavy work inside the webhook request

For a small application, synchronous processing may be fine.

As the number of repositories/events grows, I'd put a queue between the webhook endpoint and the actual processing:

GitHub
  ↓
Webhook API
  ↓
Signature validation
  ↓
Event DB / Queue
  ↓
Workers
  ├── Update local database
  ├── Fetch additional GitHub data
  └── Trigger application logic

This prevents a slow GitHub API request or temporary database problem from causing the webhook request itself to fail.

GitHub also recommends asynchronous webhook handling with a queue for higher-volume applications.

4. REST vs GraphQL

I wouldn't choose GraphQL simply because it's "better."

For webhook-driven processing, REST is often the simpler choice because GitHub provides straightforward endpoints for resources such as:

• pull requests
• reviews
• issues
• repositories
• commits

I'd use GraphQL when I need to retrieve several related pieces of data efficiently or want to avoid making many REST requests.

So my general rule would be:

REST → straightforward resource lookup

GraphQL → complex/related data requirements where reducing round trips is valuable

The important thing is to measure API usage rather than automatically choosing one.

5. Authentication and rate limits

For a GitHub App, I'd authenticate API requests using an installation access token appropriate to the installation rather than using a personal access token.

Installation tokens expire after one hour, so the application should have a mechanism for obtaining a fresh token when necessary.

I'd also:

• Request only the permissions the App actually needs.
• Cache/reuse installation tokens until they expire.
• Respect rate-limit headers.
• Implement exponential backoff for transient failures and rate limiting.
• Avoid fetching data that is already available in the webhook.
• Batch/aggregate work where possible.

GitHub App installation rate limits are also tied to the installation and can scale based on repositories/users, so designing around unnecessary API calls becomes increasingly important as the App grows.

6. Webhook security

The webhook endpoint should not simply trust any POST request.

I'd configure a strong webhook secret and verify the X-Hub-Signature-256 HMAC signature against the raw request body before processing the event.

The secret should be stored securely and never committed to the repository. GitHub specifically recommends validating webhook signatures before processing deliveries.

7. Handling missed/failed events

I'd keep an event/delivery record containing things such as:

delivery_id
installation_id
repository_id
event_type
action
received_at
processed_at
status
retry_count
error

Then failed jobs can be retried independently.

I'd also monitor failed webhook deliveries and have a recovery/reconciliation mechanism. GitHub provides APIs to list and redeliver GitHub App webhook deliveries, which can help with operational recovery.

For particularly important data, I would also consider periodic reconciliation—for example, periodically comparing the application's local state with GitHub's current state. That protects you against bugs or events missed while your service was unavailable.

8. The main principle

The design I'd aim for is:

Webhook = "Something changed."

Webhook payload = "Here's some information about what changed."

API = "Give me the additional/current state I need."

Queue = "Process this reliably even if my application/API/database is temporarily unavailable."

Database = "Remember what I've already processed."

This approach keeps the webhook endpoint fast, reduces unnecessary API calls, makes duplicate/out-of-order deliveries manageable, and gives you a much better path to scaling from a few repositories to thousands.

For a small GitHub App, you don't necessarily need all of this on day one. I'd start with webhook validation + idempotent processing + installation authentication, then introduce a queue and reconciliation process when the event volume or reliability requirements justify it.

I'd use webhooks as the trigger and the API as the source of additional data. The webhook payload often contains enough information to handle simple events, but I'd fetch the full resource when I need more details or the payload isn't sufficient.

For reliability, I'd put incoming events into a queue, acknowledge them quickly, and process them asynchronously. I'd also store the delivery ID to prevent duplicate processing, and use retries with exponential backoff for temporary failures.

REST is a good default for straightforward requests, while GraphQL is useful when you need several related resources or want to reduce the number of API calls.

For authentication, use GitHub App installation tokens rather than personal access tokens. Verify webhook signatures, respect rate limits, and monitor failed deliveries. As the number of repositories grows, a queue, idempotent handlers, and per-installation rate-limit tracking become increasingly important.